Cost Book

Read current and historical product costs, compare exact product and supplier context, and maintain verified direct or constructed Cost Book entries.

Cost Book routes work with exact product and supplier ids. Amounts use decimal-string cents per product base unit in the organization's base currency, preserving precision from source through readback.

Endpoints

Reads require cost-book-entries:read. Writes require cost-book-entries:write. The acting user's current ShelfCycle Cost Book access is checked on every request. GET /me reports effectiveCapabilities.costBookEntries.view, effectiveCapabilities.costBookEntries.create, and Cost Book write readiness.

Read current Cost Book entries

GET /cost-book-entries defaults to the current view. Narrow by productId, supplierId, or both when the workflow knows the product and supplier it needs.

curl "$SHELFCYCLE_API_BASE_URL/cost-book-entries?productId=product-id&supplierId=supplier-id&asOf=2026-07-17" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "X-ShelfCycle-Client: Supplier quote review"

Each complete entry identifies its product, supplier, effective dates, direct or constructed shape, starting cost, additional costs, total cost, provenance, and completeness. Use meta.matchStatus, meta.completeness, and meta.warnings together. A missing or unresolved amount remains null, so callers can distinguish unavailable cost from a real zero.

For the full history of one product and supplier pair, send view=history with both productId and supplierId:

curl "$SHELFCYCLE_API_BASE_URL/cost-book-entries?view=history&productId=product-id&supplierId=supplier-id&limit=25" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"

History can include current and superseded entries, their effective windows, and any unresolved construction details. When meta.hasMore is true, continue with meta.nextCursor as the only query parameter.

Understand direct and constructed costs

A direct entry begins with one entered material or landed cost and has no additional components.

A constructed entry begins with either:

• an entered material or landed cost; or
• the Cost Book entry for an exact referenced product.

It can then add ordered freight, packaging, duty, storage, processing, handling, tax, or other components. Components can use a percentage of starting cost, cents per base unit, or cents per package. Read resolvedContribution, additionalCostTotal, and totalCost as decimal strings.

Compare product and supplier cost context

Use the cost-context endpoint after resolving an exact active product and supplier:

curl "$SHELFCYCLE_API_BASE_URL/products/product-id/cost-context?supplierId=supplier-id&asOf=2026-07-17" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "X-ShelfCycle-Client: Supplier quote review"

The response brings together:

• the current and prior Cost Book entries;
• the latest completed-purchase material and landed evidence;
• the latest open-purchase-order material evidence;
• comparison amounts and percentages when the currency, base unit, cost basis, and timing align; and
• expectedCurrentEntryId for a later write.

Purchase evidence is presented as context alongside the Cost Book entry. Use each value's comparisonBasis and the comparison's comparable, reason, and temporalRelation fields before describing a change. Missing evidence remains null.

Check a Cost Book update

Submit the intended request with dryRun=true to see normalized construction, the predicted entry, current-to-proposed comparisons, readiness checks, and warnings without writing.

curl "$SHELFCYCLE_API_BASE_URL/cost-book-entries?dryRun=true" \
  -X POST \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: supplier-quote-2026-0717-line-4" \
  -d '{
    "productId": "11111111-1111-4111-8111-111111111111",
    "supplierId": "22222222-2222-4222-8222-222222222222",
    "expectedCurrentEntryId": null,
    "effectiveFrom": "2026-07-17",
    "effectiveTo": null,
    "sourceRef": "supplier-quote-2026-0717-line-4",
    "construction": {
      "type": "direct",
      "basis": "material",
      "uom": "POUND",
      "costPerBaseUomCents": "49.5"
    }
  }'

Use the current entry id returned by the exact product and supplier read or cost-context response. Send null only when the current read reports that no entry exists. If the current entry changes, fetch it again before preparing a new request.

Execute and keep the receipt

When the readiness response is ready and the workflow's policy allows the update, send the same body without dryRun=true. Keep the same stable Idempotency-Key for retries of that exact payload.

The first successful update returns the full Cost Book entry with resultAction and idempotencyStatus. A retry with the same key and body returns the original result. Preserve that receipt as the write readback, then use the verification path when the key also has read access.