Items API

GET /items

List Items

List items with optional filters. status: exact status to show (e.g. "sold", "archived", "available"). Pass "all" to skip status filtering entirely. Default (None): exclude sold + archived from results. category: exact category to filter on. filter: semantic filter. "low_stock" keeps only items at or below their reorder point (see celerp.services.reorder.is_below_reorder). on_memo_to: customer contact_id. Scope to items currently out on memo to that customer, valued (holding_value) at the price they were quoted. consigned_from: supplier contact_id. Scope to items currently held on consignment from that supplier, valued (holding_value) at cost. When a contact scope is active the response also carries value_total, the sum of holding_value over the whole scoped set (pre-pagination).

Parameters

Responses

Example

curl -X GET http://localhost:8000/items \
  -H "Authorization: Bearer $TOKEN"

POST /items

Post Item

Request body

Responses

Example

curl -X POST http://localhost:8000/items \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /items/bulk/delete

Bulk Delete

Request body

Responses

Example

curl -X POST http://localhost:8000/items/bulk/delete \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /items/bulk/expire

Bulk Expire

Request body

Responses

Example

curl -X POST http://localhost:8000/items/bulk/expire \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /items/bulk/make-available

Bulk Make Available

Commit one or more drafts into stock. Same authority as authoring the draft (edit_inventory) - no extra permission.

Request body

Responses

Example

curl -X POST http://localhost:8000/items/bulk/make-available \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /items/bulk/revert-to-draft

Bulk Revert To Draft

assert_status_change_allowed does the real gating (revert_items_to_draft + clean history).

Request body

Responses

Example

curl -X POST http://localhost:8000/items/bulk/revert-to-draft \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /items/bulk/shopify-sync

Bulk Shopify Sync

Opt the selected items into (or out of) outbound Shopify sync by emitting shop.sync.enabled/disabled, which sets is_sync_to_shopify on each item's projection.

Request body

Responses

Example

curl -X POST http://localhost:8000/items/bulk/shopify-sync \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /items/bulk/status

Bulk Set Status

Request body

Responses

Example

curl -X POST http://localhost:8000/items/bulk/status \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /items/bulk/transfer

Bulk Transfer

Request body

Responses

Example

curl -X POST http://localhost:8000/items/bulk/transfer \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

GET /items/categories

List Item Categories

Return distinct non-empty category values: union of category_schemas keys and item projections.

Responses

Example

curl -X GET http://localhost:8000/items/categories \
  -H "Authorization: Bearer $TOKEN"

GET /items/export/csv

Export Items Csv

Parameters

Responses

Example

curl -X GET http://localhost:8000/items/export/csv \
  -H "Authorization: Bearer $TOKEN"

GET /items/field-values

Get Field Values

Return sorted distinct non-empty values for a categorical item field. Allowed fields: - Fields in _SUGGESTION_FIELDS (core categorical fields) - Any attribute field (any field stored under item.attributes) - these are module-defined and can include gemstone fields, restaurant fields, etc. Blocked fields: FK references, free-text blobs, internal identifiers. Returns {"values": [...]} so the caller can safely extend without breakage.

Parameters

Responses

Example

curl -X GET http://localhost:8000/items/field-values \
  -H "Authorization: Bearer $TOKEN"

POST /items/import/batch

Batch Import Items

Batch-import CIF item records. Idempotent on idempotency_key. Max 500 per call. The raw-event-batch transport: records arrive already shaped by the caller. The committer lives in services.commit_import_batch, shared with /import/rows and the agent /import/commit.

Request body

Responses

Example

curl -X POST http://localhost:8000/items/import/batch \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

GET /items/import/batches

List Import Batches

List all import batches for this company, newest first.

Responses

Example

curl -X GET http://localhost:8000/items/import/batches \
  -H "Authorization: Bearer $TOKEN"

POST /items/import/batches/{batch_id}/undo

Undo Import Batch

Undo an import batch only when none of its created items changed later.

Parameters

Responses

Example

curl -X POST http://localhost:8000/items/import/batches/:batch_id/undo \
  -H "Authorization: Bearer $TOKEN"

POST /items/import/commit

Import Commit

Commit an item import previewed via /import/preview. Recomputes the preview from the stored bytes; a hash mismatch means the file or its mapping changed since the preview, refused with 409 rather than imported under stale assumptions. Any row validation error is refused with 422 and the error list; otherwise the rows go through the shared committer.

Request body

Responses

Example

curl -X POST http://localhost:8000/items/import/commit \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

GET /items/import/preview

Import Preview

Preview an uploaded item import for the browser UI.

Parameters

Responses

Example

curl -X GET http://localhost:8000/items/import/preview \
  -H "Authorization: Bearer $TOKEN"

POST /items/import/preview

Import Preview Agent

Preview an uploaded catalog with an optional caller-corrected mapping.

Request body

Responses

Example

curl -X POST http://localhost:8000/items/import/preview \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /items/import/rows

Import Rows

Commit already-mapped import rows (the browser importer's transport). Rows arrive mapped and fixed by the UI. The shared committer owns location resolution and creation, unit and quantity derivation, monetary conversion, idempotency, and the category-schema follow-up. Unmarked: this is the browser transport, not an agent capability (the agent commits through /import/commit).

Request body

Responses

Example

curl -X POST http://localhost:8000/items/import/rows \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /items/merge

Merge Items

Request body

Responses

Example

curl -X POST http://localhost:8000/items/merge \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /items/metadata

Items Metadata

Bulk item-metadata read: one entry per requested id, keyed by entity_id. Returns the same visibility-filtered flat dict GET /items/{entity_id} returns per item, minus the sold_price enrichment (list/doc/audit renderers never read it). This is a read gated by the router-level authentication; company_id is derived server-side from the JWT, never from the body, and the query is scoped to that company so it cannot read another company's items. Field/cost visibility is applied per the item's OWN category, exactly as the per-item route does, so restricted fields never leak. Unknown ids are simply absent from the result (no error, no fabricated entry).

Request body

Responses

Example

curl -X POST http://localhost:8000/items/metadata \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

GET /items/valuation

Get Valuation

Aggregate inventory valuation from projections. Optional ?category= and ?status= filters scope totals + count_by_status to that slice. on_memo_to: customer contact_id. Scope counts to items currently out on memo to that customer. consigned_from: supplier contact_id. Scope counts to items currently held on consignment. category_counts is always global (all active items) - used by the category tab bar. count_by_status is scoped to the current category/status/holdings filter - used by status cards.

Parameters

Responses

Example

curl -X GET http://localhost:8000/items/valuation \
  -H "Authorization: Bearer $TOKEN"

GET /items/{entity_id}

Get Item

Parameters

Responses

Example

curl -X GET http://localhost:8000/items/:entity_id \
  -H "Authorization: Bearer $TOKEN"

PATCH /items/{entity_id}

Patch Item

Parameters

Request body

Responses

Example

curl -X PATCH http://localhost:8000/items/:entity_id \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /items/{entity_id}/adjust

Adjust Item

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/items/:entity_id/adjust \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /items/{entity_id}/expire

Expire Item

Parameters

Responses

Example

curl -X POST http://localhost:8000/items/:entity_id/expire \
  -H "Authorization: Bearer $TOKEN"

POST /items/{entity_id}/price

Set Item Price

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/items/:entity_id/price \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

GET /items/{entity_id}/reorder-suggestion

Get Reorder Suggestion

Suggested reorder_point / reorder_qty from trailing outbound velocity. Read-only assist for the item detail / bulk dialog - the stored fields stay the single source of truth. Returns nulls when there is no outbound history (never a fabricated number). See celerp.services.reorder.suggest_reorder.

Parameters

Responses

Example

curl -X GET http://localhost:8000/items/:entity_id/reorder-suggestion \
  -H "Authorization: Bearer $TOKEN"

POST /items/{entity_id}/reserve

Reserve Item

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/items/:entity_id/reserve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /items/{entity_id}/split

Split Item

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/items/:entity_id/split \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

GET /items/{entity_id}/split-preview

Split Preview

Parameters

Responses

Example

curl -X GET http://localhost:8000/items/:entity_id/split-preview \
  -H "Authorization: Bearer $TOKEN"

POST /items/{entity_id}/status

Set Item Status

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/items/:entity_id/status \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /items/{entity_id}/transfer

Transfer Item

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/items/:entity_id/transfer \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /items/{entity_id}/transform

Transform Item

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/items/:entity_id/transform \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /items/{entity_id}/unreserve

Unreserve Item

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/items/:entity_id/unreserve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'