Sign in
catalog

Create a catalog entry

Creates a new catalog entry or updates an existing one if catalog_unique_key matches.

post/catalog/entries

Headers

Authorizationstring required

OAuth2 authentication flows. Auth server URLs will vary by environment

X-Api-Keystring required

API key for authentication

X-API-Versionstring

API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.

Idempotency-Keystring

Client-generated unique key (UUID/ULID recommended). JSON requests: the first 2xx response is cached for 24h and replayed on a same-key retry with a matching body; a different body returns 422. Non-JSON requests (e.g. file uploads): the key is single-use — any same-key retry returns 422 regardless of body. See Idempotency for full details.

Request body

ottimate_company_idinteger required

The Ottimate company ID this catalog entry belongs to

erp_vendor_idstring required

ERP Vendor id from ERP/accounting system

item_namestring

Item name for the catalog entry

descriptionstring

Deprecated: use item_name instead. This field will be removed in a future API version.

original_descriptionstring

Original item description from source system

skustring

SKU code

upcstring

UPC code

buying_formatstring 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.

sizestring

Pack size (e.g., '6 CT', '10 LB')

uomstring

Unit of measure (e.g., 'CASE', 'EACH', 'LB')

pricenumber double

Price for the pack size

unit_pricenumber double

Price per individual unit within the pack

is_split_caseboolean

Whether items can be purchased in split case quantities

authorized_vendorboolean

Whether the vendor is authorized for this item

catalog_unique_keystring

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_pricenumber double

Last purchased price for this item

reference_idstring

External reference ID for tracking

{"stackTrail":"paths:/catalog/entries:post:requestBody:content:application/json:schema:properties:dimensions","oasType":"schema","type":"unknown","description":"POS dimensions for this catalog entry — these are point-of-sale system dimensions, separate from ERP/accounting dimensions and not validated against your accounting configuration. Input Structure: a list of objects, each with one dimension-type key (value = dimension name) plus an optional 'code', e.g. [{\"DEPARTMENT\": \"Marketing\", \"code\": \"321654\"}]. Dimension-type keys are uppercased in the response regardless of the case submitted. Omit the field or pass null to leave dimensions unchanged."}
propertiesCatalogEntriesPostRequestBodyContentApplicationJsonSchema

Additional custom properties as key-value pairs

Response

Catalog entry created successfully

CatalogEntryObject required

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.

Changes