# Search catalog items

Full-text search over a catalog (name, SKU, description, UPC) with optional category, price-group and attribute
filters. This is the endpoint the order-entry screens use.
When `priceGroupGuid` or `orderGuid` is given, items not offered to that price group are excluded and each
item's `pricing` is reduced to that single price. A 12-digit numeric `name` performs a UPC lookup instead of a
text search.

Endpoint: POST /v1/catalog/{catalogGuid}/catalog_items/typeahead
Version: 1.19
Security: ApiKey, ApiSecret, UserGuid, UserToken, SupplierGuid

## Security:

  - `ApiKey` (unknown)
    apiKey in header x-apiKey

  - `ApiSecret` (unknown)
    apiKey in header x-apiSecret

  - `UserGuid` (unknown)
    apiKey in header userGuid

  - `UserToken` (unknown)
    apiKey in header userToken

  - `SupplierGuid` (unknown)
    apiKey in header supplierGuid

## Path parameters:

  - `catalogGuid` (string, required)
    GUID of the catalog. Must belong to the authenticated supplier.

## Header parameters:

  - `vendorGuid` (string)
    GUID of the customer (vendor) to act for. With API key authentication this selects the customer context; with user session headers it is the vendor the user is acting on behalf of.

## Request fields (application/json):

  - `name` (string)
    Search term. Matches name, SKU and description. Empty string returns the first page of the catalog.
    Example: widget

  - `catalogItemGuid` (string)
    Return exactly this item (scoped to the catalog). Text, category, paging and price-range filters are ignored; `onlyActive`, `onlyWithSerials`, price-group narrowing and the `include*` flags still apply.

  - `limit` (integer)

  - `offset` (integer)
    Zero-based page number.

  - `priceGroupGuid` (string)
    Return only items offered to this price group, with `pricing` reduced to that group's price.

  - `orderGuid` (string)
    Use the price group of this order (alternative to `priceGroupGuid`).

  - `categoryGuid` (string)

  - `categoryId` (integer)

  - `includeSubcategories` (boolean)
    With a category filter, also match items in its subcategories.

  - `onlyActive` (boolean)

  - `onlyWithSerials` (boolean)

  - `includeTotal` (boolean)
    Populate `totalCatalogItems` (costs an extra count query).

  - `includeKitItems` (boolean)

  - `includeAttributes` (boolean)

  - `includeOptions` (boolean)

  - `includeRootCategories` (boolean)
    Also return the catalog's root categories in `categories`.

  - `ignoreProductGroups` (boolean)
    Return individual items instead of their product groups.

  - `singleWildcard` (boolean)
    Match `PHRASE%` (prefix) instead of `%PHRASE%` (contains).

  - `priceRange` (object)

  - `priceRange.minPrice` (number)

  - `priceRange.maxPrice` (number)

  - `priceRange.priceField` (string)
    Field to filter on when no price group is given. Defaults to `msrp`.
    Enum: "msrp", "map", "cost_per_uom", "min_price"

  - `options` (object)
    Field-level search switches and attribute filters.

  - `options.searchName` (boolean)

  - `options.searchSku` (boolean)

  - `options.searchDescription` (boolean)

  - `options.searchUpc` (boolean)

  - `options.attributes` (object)
    Attribute name to required value (string, number, boolean, range object or list).

  - `state` (string)
    Opaque value echoed back in the response, for correlating concurrent requests.

## Response 200:

  - `200` (unknown)
    Matching catalog items.

## Response 200 fields (application/json):

  - `catalog_items` (array, required)

  - `catalog_items.id` (integer)

  - `catalog_items.guid` (string)

  - `catalog_items.catalog_id` (integer)

  - `catalog_items.category_id` (integer)

  - `catalog_items.sku` (string)

  - `catalog_items.upc` (string)

  - `catalog_items.name` (string)

  - `catalog_items.description` (string)

  - `catalog_items.manufacturer` (string)

  - `catalog_items.color` (string)

  - `catalog_items.style` (string)

  - `catalog_items.active` (boolean)

  - `catalog_items.is_taxable` (boolean)

  - `catalog_items.msrp` (number)

  - `catalog_items.cost_per_uom` (number)
    Supplier cost. Omitted for customer (vendor) users.

  - `catalog_items.pricing` (object)
    Price per price group, keyed by price group name. `"N/A"` means not offered to that group.
    Example: {"Retail":99.99,"Wholesale":79.99,"Distributor":"N/A"}

  - `catalog_items.has_inventory` (boolean)
    Whether stock is tracked for this item.

  - `catalog_items.qty_on_hand` (number)

  - `catalog_items.qty_incoming` (number)

  - `catalog_items.reserved_qty_on_hand` (number)

  - `catalog_items.qty_backordered` (number)

  - `catalog_items.qty_held_for_backorders` (number)

  - `catalog_items.min_qty_on_hand` (number)

  - `catalog_items.max_qty_on_hand` (number)

  - `catalog_items.min_order_qty` (number)

  - `catalog_items.allow_backorder` (boolean)

  - `catalog_items.qty_break` (number)
    Quantity at which `qty_break_price` applies.

  - `catalog_items.qty_break_price` (number)

  - `catalog_items.has_serials` (boolean)

  - `catalog_items.has_lots` (boolean)

  - `catalog_items.has_exp_date` (boolean)

  - `catalog_items.width` (number)

  - `catalog_items.height` (number)

  - `catalog_items.depth` (number)

  - `catalog_items.item_weight` (number)

  - `catalog_items.shipping_weight` (number)

  - `catalog_items.is_product_group` (boolean)

  - `catalog_items.product_group_type` (string)
    Enum: "flat", "multi", "null"

  - `catalog_items.product_group_display_style` (string)

  - `catalog_items.group_parent_catalog_item_id` (integer)

  - `catalog_items.group_sequence` (integer)

  - `catalog_items.group_title` (string)

  - `catalog_items.subsection_id` (integer)

  - `catalog_items.third_party_sku` (string)

  - `catalog_items.third_party_pricing` (string)

  - `catalog_items.third_party_size` (string)

  - `catalog_items.Category` (object)

  - `catalog_items.Category.id` (integer)

  - `catalog_items.Category.guid` (string)

  - `catalog_items.Category.catalog_id` (integer)

  - `catalog_items.Category.parent_category_id` (integer)

  - `catalog_items.Category.name` (string)

  - `catalog_items.Category.sequence` (integer)

  - `catalog_items.Category.hide_category` (boolean)

  - `catalog_items.Category.created_at` (string)

  - `catalog_items.Category.updated_at` (string)

  - `catalog_items.CategoryHierarchy` (array)
    Root-to-leaf category path, when category retrieval is not skipped.

  - `catalog_items.created_at` (string)

  - `catalog_items.updated_at` (string)

  - `catalog_items.deleted_at` (string)
    Present only in delta-sync responses for soft-deleted items.

  - `totalCatalogItems` (integer)

  - `resource` (string, required)
    Example: catalog_items

  - `offset` (integer)

  - `state` (string)

  - `categories` (array)
    Root categories, when `includeRootCategories` was true.

## Response 400:

  - `400` (unknown)
    The request is malformed or references a resource the supplier does not own (for example an unknown catalog GUID).

## Response 400 fields (application/json):

  - `message` (string, required)
    Human-readable error message.
    Example: Invalid Catalog GUID

  - `error` (string)
    Underlying error detail, when available.

  - `code` (string)
    Machine-readable code for specific failures (for example `INVALID_DELTA_CURSOR`).

## Response 401:

  - `401` (unknown)
    Missing or invalid credentials.

## Response 401 fields (application/json):

  - `message` (string, required)
    Human-readable error message.
    Example: Invalid Catalog GUID

  - `error` (string)
    Underlying error detail, when available.

  - `code` (string)
    Machine-readable code for specific failures (for example `INVALID_DELTA_CURSOR`).

## Response 403:

  - `403` (unknown)
    The credentials are valid but the user lacks the access level this endpoint requires.

## Response 403 fields (application/json):

  - `message` (string, required)
    Human-readable error message.
    Example: Invalid Catalog GUID

  - `error` (string)
    Underlying error detail, when available.

  - `code` (string)
    Machine-readable code for specific failures (for example `INVALID_DELTA_CURSOR`).

## Response 500:

  - `500` (unknown)
    Unexpected server error. Some legacy endpoints return the message as `text/plain` instead of JSON.

## Response 500 fields (application/json):

  - `message` (string, required)
    Human-readable error message.
    Example: Invalid Catalog GUID

  - `error` (string)
    Underlying error detail, when available.

  - `code` (string)
    Machine-readable code for specific failures (for example `INVALID_DELTA_CURSOR`).