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

# Understanding the Portal.io Catalog

> Learn how the Portal.io catalog is organized into industries, categories, and items, and how to use the API to search, browse, and retrieve product data.

The Portal.io catalog is a shared database of AV equipment, labor items, and custom items that dealers use to build proposals. When you add a line item to a proposal option, you are pulling from this catalog. The Catalog API gives you programmatic access to search, browse, and retrieve item data — including pricing, supplier costs, stock status, specs, and linked resources like PDFs and videos.

<Warning>
  The Catalog endpoints require separate authorization beyond your standard API credentials. Contact your Portal.io representative to confirm your account has catalog API access enabled before using these endpoints.
</Warning>

## Catalog structure

The catalog is organized as a three-level hierarchy: **Industries** contain **Categories**, and categories contain **Items**. Categories can also have **Sub-categories** nested within them.

<CardGroup cols={3}>
  <Card title="Industry" icon="industry">
    Top-level grouping such as Audio, Video, Networking, or Lighting. Each industry has a unique ID and contains one or more categories.
  </Card>

  <Card title="Category" icon="folder-tree">
    A product family within an industry — for example, "AV Receivers" or "Displays" under Audio and Video respectively. Categories can contain sub-categories (e.g. "4K Displays" under "Displays").
  </Card>

  <Card title="Item" icon="box">
    An individual product, labor entry, or custom item. Items carry brand, model, pricing, supplier data, stock status, and optional extended details like specs and documentation.
  </Card>
</CardGroup>

Use the [List Categories](/api-reference/catalog/list-categories) endpoint to retrieve the full category tree. The `id` values from that response serve as filters when searching items.

## Item types

The catalog contains three types of items:

| Type         | Description                                                          | Source                         |
| ------------ | -------------------------------------------------------------------- | ------------------------------ |
| `Part`       | Physical equipment — speakers, receivers, cables, displays, etc.     | Shared Portal.io catalog       |
| `Labor`      | Labor line items representing installation time and service charges. | Your account's private library |
| `CustomItem` | Custom items you have defined in your Portal.io account.             | Your account's private library |

When searching or retrieving items, use the `ItemType` query parameter to specify which type you want. It defaults to `Part` if omitted. Labor and CustomItem lookups pull from your account's private library rather than the shared catalog.

## Pricing and supplier data

Each catalog item includes two levels of pricing information:

**MSRP** — the manufacturer's suggested retail price. This is the baseline price shown to customers on proposals. The MSRP object includes the USD value, whether it has been customized by your account, the currency, and a last-modified timestamp. Some items also carry a `futurePrice` if a price change has been announced.

**Supplier costs** — the dealer's acquisition cost from each distributor that carries the item. Each supplier entry includes the cost value, stock availability, promo status, unit of measure, and the date the price was last verified. When you retrieve an item with `ExtendedDetails=true`, you get the full list of suppliers and their costs. The default search response includes only the `defaultCost` (the primary supplier).

## Extended details

By default, item responses include the core fields: brand, model, short description, image, pricing, and category IDs. Pass `ExtendedDetails=true` on the [Get Item](/api-reference/catalog/get-item) endpoint to also receive:

* `description` — full long-form product description
* `specs` — array of name/value pairs for technical specifications
* `suppliers` — complete list of suppliers with detailed cost objects
* `pdfResourceLinks` — linked product documentation (manuals, spec sheets)
* `videoResourceLinks` — linked product videos
* `additionalImageUrls` — extra product images beyond the primary

Extended details are only available on single-item lookups, not on search results.

## Searching the catalog

The [Search Items](/api-reference/catalog/search-items) endpoint supports a combination of filters that can be used together:

* **Free text** (`SearchText`) — matches against item names, brands, and descriptions
* **Category** (`CategoryId` or `CategoryIds`) — filter by one or more category IDs from the category tree
* **Parent category** (`ParentCategoryId` or `ParentCategoryIds`) — filter by industry-level category
* **Stock status** (`IsInStock`) — show only items currently in stock
* **Favorites** (`IsFavorite`) — show only items you have marked as favorites in Portal.io

Note that `CategoryId` and `CategoryIds` are mutually exclusive (use one or the other), and the same applies to `ParentCategoryId` and `ParentCategoryIds`.

Results are paginated. Use `PageNumber` and `PageSize` to control pagination, and the `itemCount` field in the response to determine total results.

## Using catalog items in proposals

After you find items in the catalog, you add them to proposal options as line items. The typical workflow is:

1. **Browse or search** the catalog to find the equipment you need.
2. **Get item details** with `ExtendedDetails=true` if you need specs, documentation, or the full supplier list.
3. **Add line items** to an option within a proposal area. Refer to the [proposal building workflow](/concepts/proposals#building-a-proposal-with-the-api) for the full sequence.

The proposal's financial summary automatically recalculates when line items are added, using the pricing from the catalog.

<Note>
  A `204` response (not `404`) is returned when a requested item ID does not exist in the catalog. Make sure your error handling checks for this status code.
</Note>

## Available API operations

| Operation            | Endpoint                         |
| -------------------- | -------------------------------- |
| Search catalog items | `GET /public/catalog`            |
| List category tree   | `GET /public/catalog/categories` |
| Get item details     | `GET /public/catalog/{ItemId}`   |