Catalogue items

Full CRUD on catalogue items, plus a bulk upsert. A catalogue item is a product. Prices, barcodes and attachments live on its variants, so every item has at least one variant.

This API is the first place a scoped API key can manage items at all. Two fields are not exposed: users, the favourites list, and favorite, which answers for the calling person and would always read false for a key.

category and companySupplier must belong to the company in the URL. An id from another company is a 400. contract, catalogues and tags are writable and are not scope-checked today.

The list reads the database rather than the search index, so there is no search parameter here and the endpoint does not depend on Elasticsearch.

Operations

Reads need master-data:read, writes master-data:write.

• GET/api/v2/{companyId}/items/: Paginated. Sorts by English name by default, case-insensitively. ordering also accepts createdAt, article and gtin.
• POST/api/v2/{companyId}/items/: names, category and itemVariants are required, and the variant list may not be empty.
• GET/api/v2/{companyId}/items/{id}/: One item. Soft-deleted items are returned here too.
• PUT/api/v2/{companyId}/items/{id}/: Replaces the writable fields. Variants sent without an id are matched to the item's existing variants by names.en, unmatched ones are created, and variants missing from the payload are removed.
• PATCH/api/v2/{companyId}/items/{id}/: Changes only what you send. Sending itemVariants replaces the whole list under the same rules as PUT.
• DELETE/api/v2/{companyId}/items/{id}/: Soft delete. The item stays retrievable by id.
• POST/api/v2/{companyId}/items/bulk-create-update/: Up to 50 items per call, matched by id and then by names.en. Always answers 200 with per-row results.