openapi: 3.2.0 info: title: Reference Catalog API version: 1.0.0 servers: - url: https://api.ottimate.com/v1 description: Production - url: https://sandbox-api.ottimate.com/v1 description: Sandbox tags: - name: Catalog paths: /catalog/entries: get: operationId: get-catalog-entries summary: List catalog entries description: Returns a paginated list of catalog entries, filterable by company, vendor, and search term. tags: - Catalog parameters: - name: ottimate_company_id in: query description: Filter entries by company ID (required) required: true schema: type: integer - name: erp_vendor_id in: query description: Filter entries by vendor name required: false schema: type: string - name: search in: query description: Search term based on item description or name required: false schema: type: string - name: page in: query description: 'Page number (default: 1)' required: false schema: type: integer - name: limit in: query description: 'Items per page (default: 50, max: 100)' required: false schema: type: integer - name: expand in: query description: 'Comma-separated list of fields to expand. Options: prices, allowances. When used, returns full CatalogEntryObject instead of CatalogEntryBasicObject.' required: false schema: type: string - name: sku in: query description: SKU code required: false schema: type: string - name: upc in: query description: UPC code required: false schema: type: string - name: buying_format in: query description: Buying format (e.g. 'CASE', 'EACH'). Pass 'null' to filter entries that have no buying format (NULL or empty). required: false schema: type: string - name: size in: query description: Pack size (e.g. '6 CT', '10 LB') required: false schema: type: string - name: uom in: query description: Unit of measure (e.g. 'CASE', 'EACH', 'LB') required: false schema: type: string - name: price in: query description: Price for the pack size required: false schema: type: number format: double - name: unit_price in: query description: Price per individual unit within the pack required: false schema: type: number format: double - name: Authorization in: header description: OAuth2 authentication flows. Auth server URLs will vary by environment required: true schema: type: string - name: X-Api-Key in: header description: API key for authentication required: true schema: type: string - name: X-API-Version in: header description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.' required: false schema: type: string responses: '200': description: Successful response with paginated catalog entry list content: application/json: schema: $ref: '#/components/schemas/CatalogEntryListResponse' '400': description: Bad request - Invalid parameters or request format content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - Authentication required or invalid credentials content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' post: operationId: post-catalog-entries summary: Create a catalog entry description: Creates a new catalog entry or updates an existing one if catalog_unique_key matches. tags: - Catalog parameters: - name: Authorization in: header description: OAuth2 authentication flows. Auth server URLs will vary by environment required: true schema: type: string - name: X-Api-Key in: header description: API key for authentication required: true schema: type: string - name: X-API-Version in: header description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.' required: false schema: type: string - name: Idempotency-Key in: header description: '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](https://docs.ottimate.com/idempotency) for full details.' required: false schema: type: string responses: '201': description: Catalog entry created successfully content: application/json: schema: $ref: '#/components/schemas/CatalogEntryObject' '400': description: Bad request - Invalid parameters or request format content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - Authentication required or invalid credentials content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' requestBody: description: '' content: application/json: schema: type: object properties: ottimate_company_id: type: integer description: The Ottimate company ID this catalog entry belongs to erp_vendor_id: type: string description: ERP Vendor id from ERP/accounting system item_name: type: string description: Item name for the catalog entry description: type: string description: 'Deprecated: use item_name instead. This field will be removed in a future API version.' original_description: type: string description: Original item description from source system sku: type: string description: SKU code upc: type: string description: UPC code buying_format: type: - string - 'null' description: 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: type: string description: Pack size (e.g., '6 CT', '10 LB') uom: type: string description: Unit of measure (e.g., 'CASE', 'EACH', 'LB') price: type: number format: double description: Price for the pack size unit_price: type: number format: double description: Price per individual unit within the pack is_split_case: type: boolean description: Whether items can be purchased in split case quantities authorized_vendor: type: boolean description: Whether the vendor is authorized for this item catalog_unique_key: type: string description: 'Unique key used to match existing entries for upsert. If omitted, the API auto-generates a key from erp_vendor_id, sku, size, and description. Key normalization: the value is derived from the entry''s core identifying fields — the key returned in the response may differ from what you submitted. Always store and reuse the returned catalog_unique_key. Key regeneration: modifying erp_vendor_id, sku, size, or description will generate a new key that no longer matches the existing entry — the API will create a new entry instead of updating the old one, leaving the previous entry as an orphan. To avoid duplicates, store the latest catalog_unique_key from the response and include it in subsequent requests.' last_purchased_price: type: number format: double description: Last purchased price for this item reference_id: type: string description: External reference ID for tracking dimensions: 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"}]. Omit the field or pass null to leave dimensions unchanged.' properties: $ref: '#/components/schemas/CatalogEntriesPostRequestBodyContentApplicationJsonSchema' description: Additional custom properties as key-value pairs prices: type: - array - 'null' items: $ref: '#/components/schemas/CatalogEntriesPostRequestBodyContentApplicationJsonSchemaPricesItems' description: 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. allowances: type: - array - 'null' items: $ref: '#/components/schemas/CatalogEntriesPostRequestBodyContentApplicationJsonSchemaAllowancesItems' description: 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. required: - ottimate_company_id - erp_vendor_id - item_name - prices - allowances /catalog/entries/{id}: get: operationId: get-catalog-entries-id summary: Retrieve a catalog entry description: Returns detailed information for a single catalog entry. tags: - Catalog parameters: - name: id in: path description: The unique ID of the catalog entry required: true schema: type: string - name: Authorization in: header description: OAuth2 authentication flows. Auth server URLs will vary by environment required: true schema: type: string - name: X-Api-Key in: header description: API key for authentication required: true schema: type: string - name: X-API-Version in: header description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.' required: false schema: type: string responses: '200': description: Successful response with catalog entry details content: application/json: schema: $ref: '#/components/schemas/CatalogEntryObject' '404': description: Not found - Resource does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' patch: operationId: patch-catalog-entries-id summary: Update a catalog entry description: Updates an existing catalog entry by ID. tags: - Catalog parameters: - name: id in: path description: The unique ID of the catalog entry required: true schema: type: string - name: Authorization in: header description: OAuth2 authentication flows. Auth server URLs will vary by environment required: true schema: type: string - name: X-Api-Key in: header description: API key for authentication required: true schema: type: string - name: X-API-Version in: header description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.' required: false schema: type: string responses: '200': description: Catalog entry updated successfully content: application/json: schema: $ref: '#/components/schemas/CatalogEntryObject' '400': description: Bad request - Invalid parameters or request format content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden - Access denied or insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - Resource does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' requestBody: description: '' content: application/json: schema: type: object properties: erp_vendor_id: type: string description: ERP Vendor id from ERP/accounting system item_name: type: string description: Item name for the catalog entry description: type: string description: 'Deprecated: use item_name instead. This field will be removed in a future API version.' original_description: type: string description: Original item description sku: type: string description: SKU code upc: type: string description: UPC code buying_format: type: - string - 'null' description: 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: type: string description: Pack size uom: type: string description: Unit of measure price: type: number format: double description: Price unit_price: type: number format: double description: Unit price is_split_case: type: boolean description: Split case indicator authorized_vendor: type: boolean description: Whether vendor is authorized erp_vendor_name: type: - string - 'null' description: 'Optional. Human-readable vendor name attached to erp_vendor_id, sourced from the originating system. Note: reads return the resolved vendor name for the entry, which may come from upstream ERP/sync sources rather than this field. Omit to leave unchanged; pass empty string to clear.' dimensions: 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"}]. Omit the field or pass null to leave dimensions unchanged.' properties: $ref: '#/components/schemas/CatalogEntriesIdPatchRequestBodyContentApplicationJsonSchema' description: Additional properties /catalog/allowances: get: operationId: get-catalog-allowances summary: List catalog allowances description: Returns a paginated list of catalog allowances, filterable by company, catalog entry, location, and effective date. tags: - Catalog parameters: - name: ottimate_company_id in: query description: Filter allowances by company ID (required) required: true schema: type: integer - name: catalog_entry_id in: query description: Filter by catalog entry ID required: false schema: type: string - name: ottimate_location_id in: query description: Filter by location ID required: false schema: type: integer - name: effective_date in: query description: Filter allowances valid on this date (YYYY-MM-DD) required: false schema: type: string format: date - name: page in: query description: Page number (default 1) required: false schema: type: integer - name: limit in: query description: Number of results per page (default 20) required: false schema: type: integer - name: Authorization in: header description: OAuth2 authentication flows. Auth server URLs will vary by environment required: true schema: type: string - name: X-Api-Key in: header description: API key for authentication required: true schema: type: string - name: X-API-Version in: header description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.' required: false schema: type: string responses: '200': description: Successful response with paginated allowance list content: application/json: schema: $ref: '#/components/schemas/CatalogAllowanceListResponse' '400': description: Bad request - Invalid parameters or request format content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' post: operationId: post-catalog-allowances summary: Create a catalog allowance description: Creates a new catalog allowance for a catalog entry. tags: - Catalog parameters: - name: Authorization in: header description: OAuth2 authentication flows. Auth server URLs will vary by environment required: true schema: type: string - name: X-Api-Key in: header description: API key for authentication required: true schema: type: string - name: X-API-Version in: header description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.' required: false schema: type: string - name: Idempotency-Key in: header description: '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](https://docs.ottimate.com/idempotency) for full details.' required: false schema: type: string responses: '201': description: Catalog allowance created successfully content: application/json: schema: $ref: '#/components/schemas/CatalogAllowanceObject' '400': description: Bad request - Invalid parameters or request format content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - Authentication required or invalid credentials content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' requestBody: description: '' content: application/json: schema: type: object properties: ottimate_company_id: type: integer description: The Ottimate company ID this allowance belongs to catalog_entry_id: type: integer description: The ID of the catalog entry this allowance applies to allowance_type: $ref: '#/components/schemas/CatalogAllowancesPostRequestBodyContentApplicationJsonSchemaAllowanceType' description: 'Type of allowance (default: ''allowance'')' amount: type: number format: double description: Allowance amount for the pack size unit_allowance: type: number format: double description: 'Allowance amount per individual unit (default: 0)' target: $ref: '#/components/schemas/CatalogAllowancesPostRequestBodyContentApplicationJsonSchemaTarget' description: 'Allowance target: company (default), location_group, or location' ottimate_location_id: type: integer description: Location ID (required when target is location) ottimate_group_id: type: integer description: Location group ID (required when target is 15/location_group) start_date: type: string format: date-time description: Allowance effective start date (ISO 8601) end_date: type: string format: date-time description: Allowance effective end date (ISO 8601, optional) reference_id: type: string description: Unique reference ID for upsert operations required: - ottimate_company_id - catalog_entry_id - amount - start_date /catalog/allowances/{id}: patch: operationId: patch-catalog-allowances-id summary: Update a catalog allowance description: Updates an existing catalog allowance by ID. tags: - Catalog parameters: - name: id in: path description: The unique ID of the catalog allowance required: true schema: type: string - name: Authorization in: header description: OAuth2 authentication flows. Auth server URLs will vary by environment required: true schema: type: string - name: X-Api-Key in: header description: API key for authentication required: true schema: type: string - name: X-API-Version in: header description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.' required: false schema: type: string responses: '200': description: Catalog allowance updated successfully content: application/json: schema: $ref: '#/components/schemas/CatalogAllowanceObject' '400': description: Bad request - Invalid parameters or request format content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden - Access denied or insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - Resource does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' requestBody: description: '' content: application/json: schema: type: object properties: allowance_type: $ref: '#/components/schemas/CatalogAllowancesIdPatchRequestBodyContentApplicationJsonSchemaAllowanceType' description: Type of allowance amount: type: number format: double description: Allowance amount unit_allowance: type: number format: double description: Unit allowance amount target: $ref: '#/components/schemas/CatalogAllowancesIdPatchRequestBodyContentApplicationJsonSchemaTarget' description: 'Allowance target: company, location_group, or location' ottimate_location_id: type: integer description: Location ID ottimate_group_id: type: integer description: Restaurant group ID start_date: type: string format: date-time description: Start date end_date: type: string format: date-time description: End date /catalog/variances: get: operationId: get-catalog-variances summary: List catalog variances description: Returns catalog entries with price variance information from invoice items. By default, returns all items that had purchases in the specified period, including items with zero variance. Use variance_only=true to return only entries with non-zero variance. Use expand=invoice_items to include all invoice items inline (otherwise only the most recent invoice item is returned). tags: - Catalog parameters: - name: ottimate_company_id in: query description: Filter by company ID (required) required: true schema: type: integer - name: variance_only in: query description: 'If true, returns only entries with non-zero variance. Default: false (returns all items including zero variance)' required: false schema: type: boolean - name: expand in: query description: Comma-separated list of fields to expand. Supports 'invoice_items' to include all invoice items for each entry. required: false schema: type: string - name: invoice_start_date in: query description: Start of date range (YYYY-MM-DD) required: false schema: type: string format: date - name: invoice_end_date in: query description: End of date range (YYYY-MM-DD) required: false schema: type: string format: date - name: erp_vendor_ids in: query description: Comma-separated ERP vendor IDs (accounting vendor IDs) to filter variances by vendor. required: false schema: type: string - name: ottimate_location_ids in: query description: Comma-separated location IDs required: false schema: type: string - name: exception_type in: query description: Filter by variance type required: false schema: $ref: '#/components/schemas/CatalogVariancesGetParametersExceptionType' - name: page in: query description: Page number for pagination required: false schema: type: integer - name: limit in: query description: Number of items per page required: false schema: type: integer - name: Authorization in: header description: OAuth2 authentication flows. Auth server URLs will vary by environment required: true schema: type: string - name: X-Api-Key in: header description: API key for authentication required: true schema: type: string - name: X-API-Version in: header description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.' required: false schema: type: string responses: '200': description: Successful response with paginated variance list content: application/json: schema: $ref: '#/components/schemas/VarianceListResponse' '400': description: Bad request - Invalid parameters or request format content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /catalog/entries/bulk: post: operationId: post-catalog-entries-bulk summary: Bulk create/update catalog entries (async) description: 'Creates or updates multiple catalog entries asynchronously. Returns 202 with batch tracking info. Maximum 1000 entries per request. Poll GET /batch/{id}/progress for status. **Deprecation notice:** The previous synchronous bulk API has been deprecated. This async endpoint is the recommended behavior going forward — it avoids timeouts on large batches and provides progress tracking via the batch polling API.' tags: - Catalog parameters: - name: Authorization in: header description: OAuth2 authentication flows. Auth server URLs will vary by environment required: true schema: type: string - name: X-Api-Key in: header description: API key for authentication required: true schema: type: string - name: X-API-Version in: header description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.' required: false schema: type: string - name: Idempotency-Key in: header description: '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](https://docs.ottimate.com/idempotency) for full details.' required: false schema: type: string responses: '202': description: Asynchronous processing started. Poll batch_url for status. content: application/json: schema: $ref: '#/components/schemas/CatalogEntriesBulkAsyncResponse' '400': description: Bad request - Invalid parameters or request format content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - Authentication required or invalid credentials content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /catalog/allowances/bulk: post: operationId: post-catalog-allowances-bulk summary: Bulk create/update catalog allowances (async) description: 'Creates or updates multiple catalog allowances asynchronously. Returns 202 with batch tracking info. Maximum 1000 allowances per request. Poll GET /batch/{id}/progress for status. **Deprecation notice:** The previous synchronous bulk API has been deprecated. This async endpoint is the recommended behavior going forward — it avoids timeouts on large batches and provides progress tracking via the batch polling API.' tags: - Catalog parameters: - name: Authorization in: header description: OAuth2 authentication flows. Auth server URLs will vary by environment required: true schema: type: string - name: X-Api-Key in: header description: API key for authentication required: true schema: type: string - name: X-API-Version in: header description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.' required: false schema: type: string - name: Idempotency-Key in: header description: '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](https://docs.ottimate.com/idempotency) for full details.' required: false schema: type: string responses: '202': description: Asynchronous processing started. Poll batch_url for status. content: application/json: schema: $ref: '#/components/schemas/CatalogAllowancesBulkAsyncResponse' '400': description: Bad request - Invalid parameters or request format content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - Authentication required or invalid credentials content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /catalog/prices/bulk: post: operationId: post-catalog-prices-bulk summary: Bulk create catalog prices (async) description: 'Creates multiple catalog prices asynchronously (create-only, skips duplicates). Returns 202 with batch tracking info. Maximum 1000 prices per request. Poll GET /batch/{id}/progress for status. **Deprecation notice:** The previous synchronous bulk API has been deprecated. This async endpoint is the recommended behavior going forward — it avoids timeouts on large batches and provides progress tracking via the batch polling API.' tags: - Catalog parameters: - name: Authorization in: header description: OAuth2 authentication flows. Auth server URLs will vary by environment required: true schema: type: string - name: X-Api-Key in: header description: API key for authentication required: true schema: type: string - name: X-API-Version in: header description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.' required: false schema: type: string - name: Idempotency-Key in: header description: '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](https://docs.ottimate.com/idempotency) for full details.' required: false schema: type: string responses: '202': description: Asynchronous processing started. Poll batch_url for status. content: application/json: schema: $ref: '#/components/schemas/CatalogPricesBulkAsyncResponse' '400': description: Bad request - Invalid parameters or request format content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - Authentication required or invalid credentials content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /catalog/variances/{id}/invoice-items: get: operationId: get-catalog-variances-id-invoice-items summary: Get invoice items for a catalog entry description: Returns paginated invoice items with price variances for a specific catalog entry. Use this endpoint when the expand=invoice_items response indicates has_more=true. tags: - Catalog parameters: - name: id in: path description: The catalog entry ID required: true schema: type: string - name: page in: query description: Page number required: false schema: type: integer - name: limit in: query description: 'Items per page (default: 20)' required: false schema: type: integer - name: Authorization in: header description: OAuth2 authentication flows. Auth server URLs will vary by environment required: true schema: type: string - name: X-Api-Key in: header description: API key for authentication required: true schema: type: string - name: X-API-Version in: header description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.' required: false schema: type: string responses: '200': description: Successful response with paginated invoice items content: application/json: schema: $ref: '#/components/schemas/InvoiceItemVarianceListResponse' '404': description: Not found - Resource does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /catalog/variance-batches: get: operationId: get-catalog-variance-batches summary: List exported catalog variance batches description: Returns exported Catalog Variance Manager batches for the given company. Only batches with export_status='exported' are ever returned — drafts and failed batches are excluded. The costbatch_payload in each result matches the Pyxis /costbatch format exactly. tags: - Catalog parameters: - name: ottimate_company_id in: query description: Company ID to filter by (required) required: true schema: type: integer - name: batch_number in: query description: Filter by exact batch number required: false schema: type: integer - name: exported_after in: query description: Return batches exported on or after this datetime (ISO 8601) required: false schema: type: string format: date-time - name: exported_after_utc in: query description: UTC filter. Accepts ISO 8601 with optional Z/offset, or YYYY-MM-DD[ HH:MM:SS] (assumed UTC). Takes precedence over the non-_utc variant. required: false schema: type: string format: date-time - name: exported_before in: query description: Return batches exported on or before this datetime (ISO 8601) required: false schema: type: string format: date-time - name: exported_before_utc in: query description: UTC filter. Accepts ISO 8601 with optional Z/offset, or YYYY-MM-DD[ HH:MM:SS] (assumed UTC). Takes precedence over the non-_utc variant. required: false schema: type: string format: date-time - name: page in: query description: Page number for pagination required: false schema: type: integer - name: limit in: query description: Number of items per page required: false schema: type: integer - name: Authorization in: header description: OAuth2 authentication flows. Auth server URLs will vary by environment required: true schema: type: string - name: X-Api-Key in: header description: API key for authentication required: true schema: type: string - name: X-API-Version in: header description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.' required: false schema: type: string responses: '200': description: Successful response with paginated exported batch list content: application/json: schema: $ref: '#/components/schemas/CatalogVarianceBatchListResponse' '400': description: Bad request - Invalid parameters or request format content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden - Access denied or insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /catalog/variance-batches/{id}/export: post: operationId: post-catalog-variance-batches-id-export summary: Export a catalog variance batch (local only) description: Marks the batch as exported without sending data to any external system. Sets exported_at to the current timestamp and api_status to success. Returns the exported batch with its costbatch_payload. Returns 400 if the batch is already exported. tags: - Catalog parameters: - name: id in: path description: The catalog variance batch ID (ctb_xxx) required: true schema: type: string - name: Authorization in: header description: OAuth2 authentication flows. Auth server URLs will vary by environment required: true schema: type: string - name: X-Api-Key in: header description: API key for authentication required: true schema: type: string - name: X-API-Version in: header description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.' required: false schema: type: string - name: Idempotency-Key in: header description: '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](https://docs.ottimate.com/idempotency) for full details.' required: false schema: type: string responses: '200': description: Batch successfully marked as exported content: application/json: schema: $ref: '#/components/schemas/CatalogVarianceBatchObject' '400': description: Bad request - Invalid parameters or request format content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden - Access denied or insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - Resource does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /catalog/prices: get: operationId: get-catalog-prices summary: List catalog prices description: Returns a paginated list of catalog prices, filterable by company, catalog entry, location, effective date, and price type. tags: - Catalog parameters: - name: ottimate_company_id in: query description: Filter prices by company ID (required) required: true schema: type: integer - name: catalog_entry_id in: query description: Filter by catalog entry ID required: false schema: type: string - name: ottimate_location_id in: query description: Filter by location ID required: false schema: type: integer - name: effective_date in: query description: Filter prices valid on this date (YYYY-MM-DD) required: false schema: type: string format: date - name: price_type in: query description: Filter by price type required: false schema: $ref: '#/components/schemas/CatalogPricesGetParametersPriceType' - name: page in: query description: Page number (default 1) required: false schema: type: integer - name: limit in: query description: Number of results per page (default 20) required: false schema: type: integer - name: Authorization in: header description: OAuth2 authentication flows. Auth server URLs will vary by environment required: true schema: type: string - name: X-Api-Key in: header description: API key for authentication required: true schema: type: string - name: X-API-Version in: header description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.' required: false schema: type: string responses: '200': description: Successful response with paginated price list content: application/json: schema: $ref: '#/components/schemas/Catalog_get_catalog_prices_Response_200' '400': description: Bad request - Invalid parameters or request format content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' post: operationId: post-catalog-prices summary: Create a catalog price description: Creates a new catalog price for a catalog entry. tags: - Catalog parameters: - name: Authorization in: header description: OAuth2 authentication flows. Auth server URLs will vary by environment required: true schema: type: string - name: X-Api-Key in: header description: API key for authentication required: true schema: type: string - name: X-API-Version in: header description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.' required: false schema: type: string - name: Idempotency-Key in: header description: '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](https://docs.ottimate.com/idempotency) for full details.' required: false schema: type: string responses: '201': description: Price created successfully content: application/json: schema: $ref: '#/components/schemas/CatalogPriceItem' '400': description: Bad request - Invalid parameters or request format content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - Authentication required or invalid credentials content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' requestBody: description: '' content: application/json: schema: type: object properties: ottimate_company_id: type: integer description: The Ottimate company ID this price belongs to catalog_entry_id: type: string description: The ID of the catalog entry this price applies to price: type: number format: double description: Price amount for the pack size unit_price: type: number format: double description: Price amount per individual unit (optional) price_type: $ref: '#/components/schemas/CatalogPricesPostRequestBodyContentApplicationJsonSchemaPriceType' description: 'Price type: company (default), location_group, or location' ottimate_location_id: type: integer description: Location ID (required when price_type is 'location') ottimate_group_id: type: integer description: Location group ID (required when price_type is 'location_group') start_date: type: string format: date-time description: Price effective start date (ISO 8601) end_date: type: string format: date-time description: Price effective end date (ISO 8601, optional) reference_id: type: string description: External reference ID for the price required: - ottimate_company_id - catalog_entry_id - price - start_date components: schemas: CatalogEntriesPostRequestBodyContentApplicationJsonSchemaAllowancesItemsData: type: object properties: {} description: Additional custom properties for this allowance title: CatalogEntriesPostRequestBodyContentApplicationJsonSchemaAllowancesItemsData CatalogEntryObjectDimensions: type: object properties: {} description: Resolved dimensions keyed by uppercase dimension type (e.g. DEPARTMENT, SUB_DEPARTMENT, CATEGORY, SUBCATEGORY, PROJECT, CLASS). Each value is the dimension name (or code if name is unavailable). title: CatalogEntryObjectDimensions CatalogAllowanceListResponse: type: object properties: count: type: integer results: type: array items: $ref: '#/components/schemas/CatalogAllowanceListResponseResultsItems' required: - count - results title: CatalogAllowanceListResponse CatalogItemPayload: type: object properties: {} description: Additional metadata from the catalog entry title: CatalogItemPayload CatalogAllowanceListResponseResultsItemsAllowanceType: type: string enum: - allowance - discount - rebate description: Type of allowance title: CatalogAllowanceListResponseResultsItemsAllowanceType VarianceListResponseResultsItems: type: object properties: id: type: string description: Catalog entry ID item_name: type: string sku: type: string upc: type: string pack_size: type: string erp_vendor_id: type: string description: ERP Vendor id from ERP/accounting system last_invoice_item: $ref: '#/components/schemas/VarianceListResponseResultsItemsLastInvoiceItem' required: - id - item_name title: VarianceListResponseResultsItems CatalogPriceItem: type: object properties: id: type: string description: Price ID catalog_entry_id: type: string description: Catalog entry ID ottimate_company_id: type: integer description: Company ID price: type: string description: Price amount (decimal string) unit_price: type: string description: Unit price (decimal string) price_type: type: integer description: Price type price_type_display: $ref: '#/components/schemas/CatalogPriceItemPriceTypeDisplay' description: Human-readable price type ottimate_location_id: type: integer description: Location ID ottimate_group_id: type: integer description: Location group ID start_date: type: string format: date-time description: Price start date end_date: type: string format: date-time description: Price end date reference_id: type: string description: Unique key created_date: type: string format: date-time description: Record creation date created_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of created_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". last_modified_date: type: string format: date-time description: Record last modified date last_modified_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of last_modified_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". required: - id - price - price_type - start_date description: Catalog price object title: CatalogPriceItem InvoiceItemVarianceListResponseResultsItems: type: object properties: id: type: integer invoice_id: type: integer item_name: type: string price: type: number format: double quantity: type: number format: double invoice_date: type: string format: date price_variance: type: number format: double effective_price: type: number format: double required: - id - invoice_id - item_name - price - quantity - invoice_date title: InvoiceItemVarianceListResponseResultsItems InvoiceItemVarianceListResponse: type: object properties: version: type: string description: API version count: type: integer description: Total number of invoice items page: type: integer description: Current page number limit: type: integer description: Items per page results: type: array items: $ref: '#/components/schemas/InvoiceItemVarianceListResponseResultsItems' required: - count - results description: Paginated list of invoice items with variance information title: InvoiceItemVarianceListResponse CatalogPricesBulkAsyncResponse: type: object properties: version: type: string description: API version of this response status: type: string description: Processing status batch_id: type: string description: Unique identifier for this batch job. Use to poll for progress. batch_url: type: string description: URL to poll for batch progress (GET) results_url: type: string description: URL to retrieve batch results once completed (GET) summary: $ref: '#/components/schemas/CatalogPricesBulkAsyncResponseSummary' description: Summary of the submitted request required: - version - status - batch_id - batch_url - results_url - summary description: Response returned immediately when a bulk prices request is accepted for async processing. title: CatalogPricesBulkAsyncResponse CatalogPricesBulkAsyncResponseSummary: type: object properties: count: type: integer description: Number of prices submitted for processing description: Summary of the submitted request title: CatalogPricesBulkAsyncResponseSummary CatalogEntriesPostRequestBodyContentApplicationJsonSchema: type: object properties: {} description: Additional custom properties as key-value pairs title: CatalogEntriesPostRequestBodyContentApplicationJsonSchema CatalogEntryObjectAllowancesItems: type: object properties: id: type: string description: Allowance ID allowance_type: $ref: '#/components/schemas/CatalogEntryObjectAllowancesItemsAllowanceType' description: Type of allowance amount: type: string description: Allowance amount (decimal string) unit_allowance: type: string description: Unit allowance amount (decimal string) target: type: integer description: Target code (10=company, 15=location_group, 20=location) target_type: $ref: '#/components/schemas/CatalogEntryObjectAllowancesItemsTargetType' description: Human-readable target type ottimate_location_id: type: integer description: Location ID ottimate_group_id: type: integer description: Location group ID start_date: type: string format: date-time description: Allowance start date start_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of start_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". end_date: type: string format: date-time description: Allowance end date end_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of end_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". reference_id: type: string description: Unique key created_date: type: string format: date-time description: Record creation date created_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of created_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". last_modified_date: type: string format: date-time description: Record last modified date last_modified_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of last_modified_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". required: - id - allowance_type - amount - target - start_date description: Catalog allowance object nested in catalog entry title: CatalogEntryObjectAllowancesItems CatalogAllowancesBulkAsyncResponse: type: object properties: version: type: string description: API version of this response status: type: string description: Processing status batch_id: type: string description: Unique identifier for this batch job. Use to poll for progress. batch_url: type: string description: URL to poll for batch progress (GET) results_url: type: string description: URL to retrieve batch results once completed (GET) summary: $ref: '#/components/schemas/CatalogAllowancesBulkAsyncResponseSummary' description: Summary of the submitted request required: - version - status - batch_id - batch_url - results_url - summary description: Response returned immediately when a bulk allowances request is accepted for async processing. title: CatalogAllowancesBulkAsyncResponse VarianceListResponse: type: object properties: count: type: integer results: type: array items: $ref: '#/components/schemas/VarianceListResponseResultsItems' required: - count - results title: VarianceListResponse CatalogAllowancesPostRequestBodyContentApplicationJsonSchemaTarget: type: string enum: - company - location_group - location description: 'Allowance target: company (default), location_group, or location' title: CatalogAllowancesPostRequestBodyContentApplicationJsonSchemaTarget ErrorResponse: type: object properties: code: type: string description: Human-readable error message request_id: type: string description: Unique identifier for the request message: description: Additional error details, can be an object, a string, or null. timestamp: type: string description: Timestamp when error occurred required: - code - message title: ErrorResponse CatalogPriceItemPriceTypeDisplay: type: string enum: - company - location_group - location description: Human-readable price type title: CatalogPriceItemPriceTypeDisplay CostBatchPayload: type: object properties: description: type: string description: Human-readable batch description, e.g. 'Catalog Batch 42' zone: type: string description: Geographical zone for this batch import_def_id: type: integer description: Pyxis import definition ID from the company token. Defaults to 0 if no Pyxis token is configured. external_batch_number: type: string description: String representation of the batch number start_datetime: type: string format: date-time description: Start date for this batch's price updates catalog_items: type: array items: $ref: '#/components/schemas/CatalogItemPayload' description: List of catalog items with updated costs description: Costbatch payload in the same shape as the Pyxis /costbatch endpoint. title: CostBatchPayload CatalogAllowancesIdPatchRequestBodyContentApplicationJsonSchemaTarget: type: string enum: - company - location_group - location description: 'Allowance target: company, location_group, or location' title: CatalogAllowancesIdPatchRequestBodyContentApplicationJsonSchemaTarget CatalogVarianceBatchObjectExportStatus: type: string enum: - exported description: Always 'exported' — non-exported batches are never returned by this API title: CatalogVarianceBatchObjectExportStatus CatalogPricesPostRequestBodyContentApplicationJsonSchemaPriceType: type: string enum: - company - location_group - location description: 'Price type: company (default), location_group, or location' title: CatalogPricesPostRequestBodyContentApplicationJsonSchemaPriceType CatalogEntriesBulkAsyncResponseSummary: type: object properties: count: type: integer description: Number of entries submitted for processing description: Summary of the submitted request title: CatalogEntriesBulkAsyncResponseSummary CatalogEntryObjectAllowancesItemsAllowanceType: type: string enum: - allowance - discount - rebate description: Type of allowance title: CatalogEntryObjectAllowancesItemsAllowanceType CatalogEntryObjectAllowancesItemsTargetType: type: string enum: - company - location_group - location description: Human-readable target type title: CatalogEntryObjectAllowancesItemsTargetType CatalogEntriesIdPatchRequestBodyContentApplicationJsonSchema: type: object properties: {} description: Additional properties title: CatalogEntriesIdPatchRequestBodyContentApplicationJsonSchema CatalogEntriesPostRequestBodyContentApplicationJsonSchemaAllowancesItems: type: object properties: allowance_type: type: string description: Type of allowance (e.g., 'allowance', 'rebate') allowance: type: number format: double description: Allowance amount (required) unit_allowance: type: number format: double description: Allowance per individual unit target: $ref: '#/components/schemas/CatalogEntriesPostRequestBodyContentApplicationJsonSchemaAllowancesItemsTarget' description: 'Allowance target: company (default), location_group, or location' ottimate_location_id: type: integer description: Location ID (for location-level allowances) ottimate_group_id: type: integer description: Location group ID (for location_group-level allowances) start_date: type: string format: date-time description: Allowance effective start date (ISO 8601, required) end_date: type: string format: date-time description: Allowance effective end date (ISO 8601) reference_id: type: string description: Unique key for this allowance record data: $ref: '#/components/schemas/CatalogEntriesPostRequestBodyContentApplicationJsonSchemaAllowancesItemsData' description: Additional custom properties for this allowance required: - allowance - start_date title: CatalogEntriesPostRequestBodyContentApplicationJsonSchemaAllowancesItems CatalogEntriesPostRequestBodyContentApplicationJsonSchemaPricesItemsData: type: object properties: {} description: Additional custom properties for this price title: CatalogEntriesPostRequestBodyContentApplicationJsonSchemaPricesItemsData CatalogEntriesPostRequestBodyContentApplicationJsonSchemaAllowancesItemsTarget: type: string enum: - company - location_group - location description: 'Allowance target: company (default), location_group, or location' title: CatalogEntriesPostRequestBodyContentApplicationJsonSchemaAllowancesItemsTarget VarianceListResponseResultsItemsLastInvoiceItem: type: object properties: id: type: integer price: type: number format: double invoice_date: type: string format: date price_variance: type: number format: double effective_price: type: number format: double required: - id - price - invoice_date title: VarianceListResponseResultsItemsLastInvoiceItem CatalogAllowancesIdPatchRequestBodyContentApplicationJsonSchemaAllowanceType: type: string enum: - allowance - discount - rebate description: Type of allowance title: CatalogAllowancesIdPatchRequestBodyContentApplicationJsonSchemaAllowanceType CatalogEntryListResponse: type: object properties: count: type: integer description: Total number of results results: type: array items: $ref: '#/components/schemas/CatalogEntryListResponseResultsItems' description: List of catalog entries (uses CatalogEntryBasicObject by default, CatalogEntryObject when expand is used) page: type: integer description: Current page number per_page: type: integer description: Items per page required: - count - results title: CatalogEntryListResponse CatalogEntryObjectPricesItemsPriceTypeDisplay: type: string enum: - company - location_group - location description: Human-readable price type title: CatalogEntryObjectPricesItemsPriceTypeDisplay CatalogEntryObjectPricesItems: type: object properties: id: type: string description: Price ID price: type: string description: Price amount (decimal string) unit_price: type: string description: Unit price (decimal string) price_type: type: integer description: Price type price_type_display: $ref: '#/components/schemas/CatalogEntryObjectPricesItemsPriceTypeDisplay' description: Human-readable price type ottimate_location_id: type: integer description: Location ID ottimate_group_id: type: integer description: Location group ID start_date: type: string format: date-time description: Price start date start_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of start_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". end_date: type: string format: date-time description: Price end date end_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of end_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". reference_id: type: string description: Unique key created_date: type: string format: date-time description: Record creation date created_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of created_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". last_modified_date: type: string format: date-time description: Record last modified date last_modified_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of last_modified_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". required: - id - price - price_type - start_date description: Catalog price object title: CatalogEntryObjectPricesItems CatalogAllowanceObjectTargetType: type: string enum: - company - location_group - location description: Human-readable target type title: CatalogAllowanceObjectTargetType CatalogAllowanceObjectAllowanceType: type: string enum: - allowance - discount - rebate description: Type of allowance title: CatalogAllowanceObjectAllowanceType Catalog_get_catalog_prices_Response_200: type: object properties: count: type: integer page: type: integer per_page: type: integer results: type: array items: $ref: '#/components/schemas/CatalogPriceItem' required: - count - results description: Paginated list of catalog prices title: Catalog_get_catalog_prices_Response_200 CatalogPricesGetParametersPriceType: type: string enum: - company - location_group - location title: CatalogPricesGetParametersPriceType CatalogEntriesBulkAsyncResponse: type: object properties: version: type: string description: API version of this response status: type: string description: Processing status batch_id: type: string description: Unique identifier for this batch job. Use to poll for progress. batch_url: type: string description: URL to poll for batch progress (GET) results_url: type: string description: URL to retrieve batch results once completed (GET) summary: $ref: '#/components/schemas/CatalogEntriesBulkAsyncResponseSummary' description: Summary of the submitted request required: - version - status - batch_id - batch_url - results_url - summary description: Response returned immediately when a bulk entries request is accepted for async processing. title: CatalogEntriesBulkAsyncResponse CatalogAllowanceListResponseResultsItemsTargetType: type: string enum: - company - location_group - location description: Human-readable target type title: CatalogAllowanceListResponseResultsItemsTargetType CatalogEntriesPostRequestBodyContentApplicationJsonSchemaPricesItemsPriceType: type: string enum: - company - location_group - location description: 'Price type: company (default), location_group, or location' title: CatalogEntriesPostRequestBodyContentApplicationJsonSchemaPricesItemsPriceType CatalogAllowancesBulkAsyncResponseSummary: type: object properties: count: type: integer description: Number of allowances submitted for processing description: Summary of the submitted request title: CatalogAllowancesBulkAsyncResponseSummary CatalogVarianceBatchObject: type: object properties: id: type: string description: Unique batch identifier (prefixed with ctb_) ottimate_company_id: type: integer description: Company ID this batch belongs to batch_number: type: integer description: Sequential batch number within the company export_status: $ref: '#/components/schemas/CatalogVarianceBatchObjectExportStatus' description: Always 'exported' — non-exported batches are never returned by this API exported_at: type: string format: date-time description: Timestamp when the batch was exported exported_at_utc: type: - string - 'null' format: date-time description: UTC equivalent of exported_at. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". costbatch_payload: $ref: '#/components/schemas/CostBatchPayload' required: - id - ottimate_company_id - batch_number - export_status - exported_at - costbatch_payload description: An exported Catalog Variance Manager batch. title: CatalogVarianceBatchObject CatalogVarianceBatchListResponse: type: object properties: count: type: integer description: Total number of results next: type: - string - 'null' description: URL to next page, or null previous: type: - string - 'null' description: URL to previous page, or null results: type: array items: $ref: '#/components/schemas/CatalogVarianceBatchObject' description: Paginated list of exported catalog variance batches. title: CatalogVarianceBatchListResponse CatalogEntryObjectWarningsItems: type: object properties: message: type: string description: Warning message describing the missing field title: CatalogEntryObjectWarningsItems CatalogEntryListResponseResultsItems: type: object properties: id: type: string description: Unique identifier (prefixed with cte_) ottimate_company_id: type: integer description: Company ID reference_id: type: string description: Unique key for the catalog entry item_name: type: string description: Item name for the catalog entry description: type: string description: 'Deprecated: use item_name instead. This field will be removed in a future API version.' sku: type: string description: SKU code upc: type: string description: UPC code buying_format: type: - string - 'null' description: 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. pack_size: type: string description: Pack size uom: type: string description: Unit of measure price: type: string description: Price (decimal string) unit_price: type: string description: Unit price (decimal string) last_purchased_price: type: string description: Last purchased price (decimal string) erp_vendor_id: type: string description: ERP Vendor id from ERP/accounting system ottimate_vendor_name: type: - string - 'null' description: Deprecated. Use `erp_vendor_name` instead. Same value, kept for backward compatibility; will be removed in a future API version. erp_vendor_name: type: - string - 'null' description: Human-readable vendor name attached to erp_vendor_id, sourced from the originating system. Nullable when not provided. is_split_case: type: boolean description: Split case indicator last_purchased_date: type: string description: Last purchased date last_purchased_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of last_purchased_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". created_date: type: string format: date-time description: Record creation date created_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of created_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". last_modified_date: type: string format: date-time description: Record last modified date last_modified_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of last_modified_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". required: - id - ottimate_company_id - item_name description: Basic catalog entry object returned for list operations title: CatalogEntryListResponseResultsItems CatalogEntriesPostRequestBodyContentApplicationJsonSchemaPricesItems: type: object properties: price: type: number format: double description: Price amount (required) unit_price: type: number format: double description: Price per individual unit price_type: $ref: '#/components/schemas/CatalogEntriesPostRequestBodyContentApplicationJsonSchemaPricesItemsPriceType' description: 'Price type: company (default), location_group, or location' ottimate_location_id: type: integer description: Location ID (required when price_type is 'location') ottimate_group_id: type: integer description: Location group ID (required when price_type is 'location_group') start_date: type: string format: date-time description: Price effective start date (ISO 8601) end_date: type: string format: date-time description: Price effective end date (ISO 8601) reference_id: type: string description: Unique key for this price record data: $ref: '#/components/schemas/CatalogEntriesPostRequestBodyContentApplicationJsonSchemaPricesItemsData' description: Additional custom properties for this price required: - price title: CatalogEntriesPostRequestBodyContentApplicationJsonSchemaPricesItems CatalogVariancesGetParametersExceptionType: type: string enum: - underbilling - overbilling title: CatalogVariancesGetParametersExceptionType CatalogAllowancesPostRequestBodyContentApplicationJsonSchemaAllowanceType: type: string enum: - allowance - discount - rebate description: 'Type of allowance (default: ''allowance'')' title: CatalogAllowancesPostRequestBodyContentApplicationJsonSchemaAllowanceType CatalogAllowanceListResponseResultsItems: type: object properties: id: type: string description: Unique identifier catalog_entry_id: type: string description: Associated catalog entry ID (prefixed with cte_) ottimate_company_id: type: integer description: Company ID ottimate_location_id: type: integer description: Location ID allowance_type: $ref: '#/components/schemas/CatalogAllowanceListResponseResultsItemsAllowanceType' description: Type of allowance amount: type: string description: Allowance amount (decimal string) unit_allowance: type: string description: Unit allowance amount (decimal string) target: type: integer description: Target code (10=company, 15=location_group, 20=location) target_type: $ref: '#/components/schemas/CatalogAllowanceListResponseResultsItemsTargetType' description: Human-readable target type start_date: type: string description: Start date start_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of start_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". end_date: type: string description: End date end_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of end_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". reference_id: type: string description: Unique key created_date: type: string format: date-time description: Record creation date created_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of created_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". last_modified_date: type: string format: date-time description: Record last modified date last_modified_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of last_modified_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". required: - id - catalog_entry_id - ottimate_company_id - allowance_type - amount - target - start_date description: Catalog allowance object for standalone list endpoint title: CatalogAllowanceListResponseResultsItems CatalogAllowanceObject: type: object properties: id: type: string description: Unique identifier catalog_entry_id: type: string description: Associated catalog entry ID (prefixed with cte_) ottimate_company_id: type: integer description: Company ID ottimate_location_id: type: integer description: Location ID allowance_type: $ref: '#/components/schemas/CatalogAllowanceObjectAllowanceType' description: Type of allowance amount: type: string description: Allowance amount (decimal string) unit_allowance: type: string description: Unit allowance amount (decimal string) target: type: integer description: Target code (10=company, 15=location_group, 20=location) target_type: $ref: '#/components/schemas/CatalogAllowanceObjectTargetType' description: Human-readable target type start_date: type: string format: date-time description: Start date start_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of start_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". end_date: type: string format: date-time description: End date end_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of end_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". reference_id: type: string description: Unique key created_date: type: string format: date-time description: Record creation date created_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of created_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". last_modified_date: type: string format: date-time description: Record last modified date last_modified_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of last_modified_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". required: - id - catalog_entry_id - ottimate_company_id - allowance_type - amount - target - start_date description: Catalog allowance object for standalone list endpoint title: CatalogAllowanceObject CatalogEntryObject: type: object properties: id: type: string description: Unique identifier (prefixed with cte_) ottimate_company_id: type: integer description: Company ID reference_id: type: string description: Unique key for the catalog entry item_name: type: string description: Item name for the catalog entry description: type: string description: 'Deprecated: use item_name instead. This field will be removed in a future API version.' sku: type: string description: SKU code upc: type: string description: UPC code buying_format: type: - string - 'null' description: 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. pack_size: type: string description: Pack size uom: type: string description: Unit of measure price: type: string description: Price (decimal string) unit_price: type: string description: Unit price (decimal string) last_purchased_price: type: string description: Last purchased price (decimal string) erp_vendor_id: type: string description: ERP Vendor id from ERP/accounting system ottimate_vendor_name: type: - string - 'null' description: Deprecated. Use `erp_vendor_name` instead. Same value, kept for backward compatibility; will be removed in a future API version. erp_vendor_name: type: - string - 'null' description: Human-readable vendor name attached to erp_vendor_id, sourced from the originating system. Nullable when not provided. is_split_case: type: boolean description: Split case indicator dimensions: oneOf: - $ref: '#/components/schemas/CatalogEntryObjectDimensions' - type: 'null' description: Resolved dimensions keyed by uppercase dimension type (e.g. DEPARTMENT, SUB_DEPARTMENT, CATEGORY, SUBCATEGORY, PROJECT, CLASS). Each value is the dimension name (or code if name is unavailable). display_name: type: string description: Display name for the item last_purchased_date: type: string description: Last purchased date last_purchased_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of last_purchased_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". created_date: type: string format: date-time description: Record creation date created_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of created_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". last_modified_date: type: string format: date-time description: Record last modified date last_modified_date_utc: type: - string - 'null' format: date-time description: UTC equivalent of last_modified_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z". prices: type: array items: $ref: '#/components/schemas/CatalogEntryObjectPricesItems' description: List of catalog prices (only in retrieve or when expand=prices) allowances: type: array items: $ref: '#/components/schemas/CatalogEntryObjectAllowancesItems' description: List of catalog allowances (only in retrieve or when expand=allowances) warnings: type: array items: $ref: '#/components/schemas/CatalogEntryObjectWarningsItems' description: Soft-validation warnings. Present when the prices or allowances field was absent from the request. required: - id - ottimate_company_id - item_name description: Full catalog entry object returned for retrieve operations title: CatalogEntryObject securitySchemes: OAuth2: type: http scheme: bearer description: OAuth2 authentication flows. Auth server URLs will vary by environment