--- title: "Create a catalog entry" method: POST path: "/catalog/entries" tags: ["catalog"] --- # Create a catalog entry `POST /catalog/entries` Creates a new catalog entry or updates an existing one if catalog_unique_key matches. ## Headers - `Authorization` string, required - `X-Api-Key` string, required - `X-API-Version` string - `Idempotency-Key` string ## Request body - object - `ottimate_company_id` integer, required — The Ottimate company ID this catalog entry belongs to - `erp_vendor_id` string, required — ERP Vendor id from ERP/accounting system - `item_name` string — Item name for the catalog entry - `description` string — Deprecated: use item_name instead. This field will be removed in a future API version. - `original_description` string — Original item description from source system - `sku` string — SKU code - `upc` string — UPC code - `buying_format` string, nullable — Buying format distinguishing multiple purchasing formats for the same item (e.g., 'CASE', 'EACH'). Used as part of the composite unique key for integrations that differentiate catalog entries by buying format. Optional — null or omitted for integrations that do not use buying format. - `size` string — Pack size (e.g., '6 CT', '10 LB') - `uom` string — Unit of measure (e.g., 'CASE', 'EACH', 'LB') - `price` number, double — Price for the pack size - `unit_price` number, double — Price per individual unit within the pack - `is_split_case` boolean — Whether items can be purchased in split case quantities - `authorized_vendor` boolean — Whether the vendor is authorized for this item - `catalog_unique_key` string — Optional. Used only to help match this submission to an existing entry for upsert — supplying a value does NOT set the entry's stored key. The persisted catalog_unique_key is always auto-generated from a set of identifying fields, regardless of what (if anything) you submit here; a submitted value that doesn't match the auto-generated one is silently discarded on save. Which fields make up the key depends on the company's catalog matching mode and ERP integration (for example: vendor+sku+size+item_name for Starter/default mode; vendor+upc+buying_format for Growth/Premium mode; vendor+upc for some ERP integrations regardless of mode). Key regeneration: modifying any field used in your company's key format will generate a new key that no longer matches the existing entry on a future upsert — the API will create a new entry instead of updating the old one, leaving the previous entry as an orphan. Always read catalog_unique_key from the response rather than relying on a value you submitted. - `last_purchased_price` number, double — Last purchased price for this item - `reference_id` string — External reference ID for tracking - `dimensions` unknown - `properties` CatalogEntriesPostRequestBodyContentApplicationJsonSchema — Additional custom properties as key-value pairs - `prices` CatalogEntriesPostRequestBodyContentApplicationJsonSchemaPricesItems[], nullable — Prices to create with this catalog entry. Must be present in the request — pass null to explicitly indicate no prices. Omitting this field is deprecated and will return a warning in the response. - `price` number, double, required — Price amount (required) - `unit_price` number, double — Price per individual unit - `price_type` 'company' | 'location_group' | 'location' — Price type: company (default), location_group, or location - `ottimate_location_id` integer — Location ID (required when price_type is 'location') - `ottimate_group_id` integer — Location group ID (required when price_type is 'location_group') - `start_date` string, date-time — Price effective start date (ISO 8601) - `end_date` string, date-time — Price effective end date (ISO 8601) - `reference_id` string — Unique key for this price record - `data` CatalogEntriesPostRequestBodyContentApplicationJsonSchemaPricesItemsData — Additional custom properties for this price - `allowances` CatalogEntriesPostRequestBodyContentApplicationJsonSchemaAllowancesItems[], nullable — Allowances to create with this catalog entry. Must be present in the request — pass null to explicitly indicate no allowances. Omitting this field is deprecated and will return a warning in the response. - `allowance_type` string — Type of allowance (e.g., 'allowance', 'rebate') - `amount` number, double — Allowance amount for the pack size (default: 0). Preferred over the deprecated `allowance` field; if both are sent, `amount` wins. - `allowance` number, double — Deprecated alias for `amount`. Accepted for backward compatibility for a transition period; use `amount` instead. - `unit_allowance` number, double — Allowance per individual unit - `percent_allowance` number, double — Percentage-based allowance (0-999.99). Mutually exclusive with amount and unit_allowance. - `target` 'company' | 'location_group' | 'location' — Allowance target: company (default), location_group, or location - `ottimate_location_id` integer — Location ID (for location-level allowances) - `ottimate_group_id` integer — Location group ID (for location_group-level allowances) - `start_date` string, date-time, required — Allowance effective start date (ISO 8601, required) - `end_date` string, date-time — Allowance effective end date (ISO 8601) - `reference_id` string — Unique key for this allowance record - `data` CatalogEntriesPostRequestBodyContentApplicationJsonSchemaAllowancesItemsData — Additional custom properties for this allowance ## Response `201` Catalog entry created successfully - CatalogEntryObject — Customer-supplied custom key-value properties. On every write (create or update), Ottimate also stores the raw submitted request body under a reserved "public_api_request" key inside this same object — this key is not customer data, is overwritten (not merged/accumulated) on each write to always reflect the most recent request, and will appear in read responses alongside whatever custom properties you submit. ## Other responses - `400` — Bad request - Invalid parameters or request format - `401` — Unauthorized - Authentication required or invalid credentials - `403` — Forbidden - Access denied or insufficient permissions ## Changes > 11 revisions in range; 2 could not be searched. - **2026-08-22** `75aab60eedc9` — 2 breaking, 1 warning, 1 info - for the `header` request parameter `Idempotency-Key`, the minLength was increased from `0` to `1` - added the pattern `^[A-Za-z0-9._\-+=/]{1,128}$` to the `header` request parameter `Idempotency-Key` - for the `header` request parameter `Idempotency-Key`, the maxLength was set to `128` - request property `allowances/items/allowance` deprecated - **2026-08-20** `81bcb10237c4` — 3 breaking, 25 warning - removed the required property `id` from the response with the `201` status - removed the required property `item_name` from the response with the `201` status - removed the required property `ottimate_company_id` from the response with the `201` status - removed the optional property `allowances` from the response with the `201` status - …24 more - **2026-08-19** `c0b5cf6c7a72` — 3 info - added the new optional request property `allowances/items/amount` - the `allowance` request property default value `0` was removed - added the non-success response with the status `403` - …earlier changes not shown [Full history](https://skmtc.dev/ottimate/apis/api-reference/changes/catalog/entries/post.md) --- [API](https://skmtc.dev/ottimate/apis/api-reference.md) · [All operations](https://skmtc.dev/ottimate/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ottimate/api-reference/revisions/ba91ff4c6969/schema)