> 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.

# Managing your catalog

> How to add, update, and look up products in the Truemed product catalog using the API.

Use the Product Catalog API to keep Truemed's view of your product catalog in sync with your own.
The API supports adding new products, updating existing ones, and looking up current eligibility
status for individual SKUs.

> **Note**
>
> ## Before items go live
>
> Submit your products to Truemed before launching them to customers, ensuring no missed opportunities.

## Adding a new product

Call [`create_catalog_item`](/api-reference/product-catalog/create-item) to register a new SKU
with Truemed. Include as much product detail as possible—name, description, GTIN, image URLs—so
Truemed can classify it accurately.

```json
POST /api/v1/product_catalog/items/create
{
  "sku": "ITEM-001",
  "name": "Compression Knee Brace",
  "description": "Medical-grade compression support for knee pain relief.",
  "url": "https://example.com/products/knee-brace",
  "gtin": "00012345678905",
  "image_urls": ["https://example.com/images/knee-brace.jpg"]
}
```

Truemed classifies items asynchronously. You'll receive a
[`product_catalog_item_eligibility_updated`](/api-reference/product-catalog/item-eligibility-updated-webhook)
webhook when classification is complete. Store that status in your system and use it to control
where Truemed appears in your storefront.

> **Note**
>
> Each SKU must be unique per merchant account. Attempting to create a duplicate SKU will
> return a `409 Conflict` error.

## Updating a product

Call [`update_catalog_item`](/api-reference/product-catalog/update-item) when a product's
details change—such as a name change, updated description, or new image. Truemed will
re-evaluate eligibility based on the updated information.

```json
POST /api/v1/product_catalog/items/update
{
  "sku": "ITEM-001",
  "name": "Compression Knee Brace – Medical Grade",
  "description": "Updated description with additional clinical detail.",
  "url": "https://example.com/products/knee-brace",
  "image_urls": ["https://example.com/images/knee-brace-updated.jpg"]
}
```

## Looking up a product

Call [`get_catalog_item`](/api-reference/product-catalog/get-item-detail) to retrieve a
product's current eligibility status and details by SKU.

```json
POST /api/v1/product_catalog/items/detail
{
  "sku": "ITEM-001"
}
```

The response includes the item's full product details. The `eligibility` field contains the
current HSA/FSA status (`eligible`, `eligible_with_lmn`, or `ineligible`), or `null` if
the item is still awaiting review.

The response also carries `comparable_item_price_cents`: the price, in cents, of an everyday
equivalent product. Truemed deducts this comparable amount from each unit of the item before any of
its price reaches an HSA/FSA card, up to the unit price. Truemed returns it only on an item it can
charge to an HSA/FSA card that also has a comparable product on file, and omits it for an ineligible
item, for one still awaiting review, and for one with no comparable product attached.
[`list_catalog_items`](/api-reference/product-catalog/list-catalog-items) returns it on the same
terms.

Truemed reviews comparable amounts about monthly. The eligibility webhook carries the comparable
amount as of each delivery, but a reprice triggers no delivery and does not advance `updated_at`.
Re-read the full catalog at least monthly. Truemed settles the charged amount at checkout.

## Bulk uploads

For initial catalog ingestion or large-scale updates, use the [bulk upload tool](/guides/troubleshooting/sku-upload) in your
Truemed Partner Dashboard instead of calling the API item by item.

## Staying in sync

Keeping your catalog in sync requires all three of these actions. Omitting any one of them will
cause your local eligibility data to drift out of date:

1. **Listen to the webhook.** Subscribe to
   [`product_catalog_item_eligibility_updated`](/api-reference/product-catalog/item-eligibility-updated-webhook)
   and update your local eligibility records whenever Truemed's classification changes. This is
   the only way to learn about status updates—Truemed does not push changes through any other
   channel. The item is at `data.data.object` on signed deliveries and `data.object` on unsigned ones.
2. **Update on attribute changes.** Call
   [`update_catalog_item`](/api-reference/product-catalog/update-item) whenever a
   product's name, description, images, or other details change in your system. Truemed
   re-evaluates eligibility after any update.
3. **Register new products immediately.** Call
   [`create_catalog_item`](/api-reference/product-catalog/create-item) for every new
   product added to your store—ideally before the product goes live, so classification can
   complete before customers see it.