> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://developers.truemed.com/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.truemed.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.truemed.com/_mcp/server.

# List Catalog Items

GET https://dev-api.truemed.com/api/v1/product_catalog/items/list

Lists catalog items for the authenticated merchant, including current HSA/FSA eligibility for each item.

This endpoint is intended to complement the `Item Eligibility Updated` webhook: use the webhook to receive ongoing updates, and use this endpoint to enumerate items that were already categorized before webhook ingestion began (or to reconcile after a gap).

Use `eligibility` to scope the response to a specific eligibility state, and `updated_after` to incrementally sync only items changed since the last poll.

### Computing the HSA/FSA-eligible amount

Items eligible only for the margin over an everyday equivalent carry that equivalent's price as `comparable_item_price_cents`:

```
eligible_amount = max(0, unit_price - comparable_item_price_cents) * quantity
```

It is absent when the full price is eligible, and when the item cannot be charged to an HSA/FSA card.

### Keeping `comparable_item_price_cents` current

Truemed reviews these prices about monthly. A change fires no webhook and does not advance `updated_at`, so re-read the catalog in full at least monthly. The charged amount is settled at checkout.

Reference: https://developers.truemed.com/api-reference/product-catalog/list-catalog-items

## Authentication

- `x-truemed-api-key` header (required) — Sales channel API key for merchant server-to-server authentication

## Servers

- `https://dev-api.truemed.com` (Development server, default)
- `https://api.truemed.com` (Production server)

## Request

### Query parameters

- `page` (integer, optional) — Optional field indicating which page to access. Defaults to 1.
- `page_size` (integer, optional) — Optional field indicating the number of records per page. Defaults to 30.
- `eligibility` (string, optional) — Filter results to items whose eligibility matches the given value. Items that have no eligibility yet are excluded when this filter is set.
- `updated_after` (datetime, optional) — Return only catalog items whose last update is at or after this ISO 8601 timestamp. Useful for incremental sync after `Item Eligibility Updated` webhooks.

## Response

### 200

Successful response

- `data` (list of CatalogItemDetail, required) — An array of catalog item objects for the current page.
- `pagination` (PaginationBody, optional, nullable) — A pagination object with information about the current page, page size, total count, and last page.

## Errors

### 400 Bad Request Error

Bad Request

- `error` (enum, required)
  - Allowed values: `TotalAmountInvalid`, `ValidationError`
- `message` (string, required)

### 404 Not Found Error

Not Found

- `error` (enum, required)
  - Allowed values: `NotFound`
- `message` (string, required)

### 405 Method Not Allowed Error

Method Not Allowed

- `error` (enum, required)
  - Allowed values: `MethodNotAllowed`
- `message` (string, required)

### 500 Internal Server Error

Internal Server Error

- `error` (enum, required)
  - Allowed values: `ServerError`
- `message` (string, required)

### 501 Not Implemented Error

Not Implemented

- `error` (enum, required)
  - Allowed values: `NotImplemented`
- `message` (string, required)

## Types

### CatalogItemDetail

- `created_at` (datetime, required) — The date and time the catalog item was created.
- `name` (string, required) — The name of the catalog item.
- `sku` (string, required) — The SKU of the catalog item.
- `comparable_item_price_cents` (integer, optional, nullable) — The amount, in cents, deducted from each unit of this item before any of it can reach an HSA/FSA card.
- `description` (string, optional, nullable) — An optional description of the catalog item.
- `eligibility` (enum, optional, nullable) — HSA/FSA eligibility status for the catalog item.
  - Allowed values: `eligible`, `eligible_with_lmn`, `ineligible`
- `gtin` (string, optional, nullable) — The GTIN of the catalog item.
- `image_urls` (list of string, optional, nullable) — Optional array of image URLs associated with the catalog item.
- `metadata` (string, optional, nullable) — Optional metadata string for the catalog item.
- `product_id` (string, optional, nullable) — The product ID of the product which this catalog item is a variant of.
- `reviewed_at` (datetime, optional, nullable) — The date and time the catalog item's eligibility was last decided. Present whenever `eligibility` is.
- `url` (string, optional, nullable) — An optional display page URL for the catalog item.

### PaginationBody

- `count` (integer, required) — The total number of items associated with the provided API key.
- `current_page` (integer, required) — The page requested. If none was provided, this will default to 1.
- `last_page` (integer, required) — The last page. You can iterate through pages by providing integers up to last_page in the page parameter.
- `page_size` (integer, required) — The number of items per page applied to this response.

## Examples

**Response**

```json
{
  "data": [
    {
      "created_at": "2024-01-15T09:30:00Z",
      "name": "string",
      "sku": "string",
      "comparable_item_price_cents": 1,
      "description": "string",
      "eligibility": "eligible",
      "gtin": "string",
      "image_urls": [
        "string"
      ],
      "metadata": "string",
      "product_id": "string",
      "reviewed_at": "2024-01-15T09:30:00Z",
      "url": "string"
    }
  ],
  "pagination": {
    "count": 1,
    "current_page": 1,
    "last_page": 1,
    "page_size": 1
  }
}
```

**SDK Code**

```python
import requests

url = "https://dev-api.truemed.com/api/v1/product_catalog/items/list"

headers = {"x-truemed-api-key": "<apiKey>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://dev-api.truemed.com/api/v1/product_catalog/items/list';
const options = {method: 'GET', headers: {'x-truemed-api-key': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```