> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automate.ax/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Automate.ax automations are TypeScript programs.
> Use Bun for installation and command examples.
> Use Automate.ax for the product name and automate.ax for the package, CLI, and domain.
> Treat documented public APIs as current; do not invent transitional or deprecated names.

# Search Catalog Items

> Searches for catalog items or item variations by matching supported search attribute values, including custom attribute values, against one or more of the specified query filters.

`square.searchCatalogItems` searches for catalog items or item variations by matching supported search attribute values, including custom attribute values, against one or more of the specified query filters.

## Example

```ts automations/square-search-catalog-items.automation.ts theme={null}
import { automation, onDashboardRun } from "automate.ax"
import { square } from "automate.ax/square"

export default automation("Search Square Catalog Items", () => {
  onDashboardRun({ title: "Search Square Catalog Items" })

  square.searchCatalogItems({
    textFilter: "red",
    categoryIds: ["WINE_CATEGORY_ID"],
    stockLevels: ["OUT", "LOW"],
    enabledLocationIds: ["ATL_LOCATION_ID"],
    limit: 100,
    sortOrder: "ASC",
    productTypes: ["REGULAR"],
    customAttributeFilters: [
      {
        customAttributeDefinitionId: "VEGAN_DEFINITION_ID",
        boolFilter: true,
      },
      {
        customAttributeDefinitionId: "BRAND_DEFINITION_ID",
        stringFilter: "Dark Horse",
      },
      {
        key: "VINTAGE",
        numberFilter: {
          min: "min",
          max: "max",
        },
      },
      {
        customAttributeDefinitionId: "VARIETAL_DEFINITION_ID",
      },
    ],
  })
})
```

## Inputs

Every input accepts a compatible signal. It requires `ITEMS_READ`.

| Field                    | Type                                           | Required | Default | Description                                                                                                                                                                                                                                  |
| ------------------------ | ---------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `textFilter`             | `string`                                       | No       | —       | The text filter expression to return items or item variations containing specified text in the `name`, `description`, or `abbreviation` attribute value of an item, or in the `name`, `sku`, or `upc` attribute value of an item variation.  |
| `categoryIds`            | `string[]`                                     | No       | —       | The category id query expression to return items containing the specified category IDs.                                                                                                                                                      |
| `stockLevels`            | `Square.SearchCatalogItemsRequestStockLevel[]` | No       | —       | The stock-level query expression to return item variations with the specified stock levels. See [SearchCatalogItemsRequestStockLevel](#type-searchcatalogitemsrequeststocklevel) for possible values                                         |
| `enabledLocationIds`     | `string[]`                                     | No       | —       | The enabled-location query expression to return items and item variations having specified enabled locations.                                                                                                                                |
| `cursor`                 | `string`                                       | No       | —       | The pagination token, returned in the previous response, used to fetch the next batch of pending results.                                                                                                                                    |
| `limit`                  | `number`                                       | No       | 100     | The maximum number of results to return per page. The default value is 100.                                                                                                                                                                  |
| `sortOrder`              | `Square.SortOrder`                             | No       | —       | The order to sort the results by item names. The default sort order is ascending (`ASC`). See [SortOrder](#type-sortorder) for possible values                                                                                               |
| `productTypes`           | `Square.CatalogItemProductType[]`              | No       | —       | The product types query expression to return items or item variations having the specified product types.                                                                                                                                    |
| `customAttributeFilters` | `Square.CustomAttributeFilter[]`               | No       | —       | The customer-attribute filter to return items or item variations matching the specified custom attribute expressions. A maximum number of 10 custom attribute expressions are supported in a single call to the SearchCatalogItems endpoint. |
| `archivedState`          | `Square.ArchivedState`                         | No       | —       | The query filter to return not archived (`ARCHIVED_STATE_NOT_ARCHIVED`), archived (`ARCHIVED_STATE_ARCHIVED`), or either type (`ARCHIVED_STATE_ALL`) of items.                                                                               |
| `includeOptions`         | `Square.IncludeOptions`                        | No       | —       | Options to include related resources in the response.                                                                                                                                                                                        |

Use the official [SearchCatalogItems reference](https://developer.squareup.com/reference/square/catalog-api/search-catalog-items) for provider field semantics and limits.

## Output

Returns the official `Square.SearchCatalogItemsResponse` response as a codec-safe object. Square integer money amounts remain `bigint` values.