Managing Your Catalog via 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.

Adding a new product

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

1
POST /api/v1/product_catalog/items/create
2
{
3
  "sku": "ITEM-001",
4
  "name": "Compression Knee Brace",
5
  "description": "Medical-grade compression support for knee pain relief.",
6
  "url": "https://example.com/products/knee-brace",
7
  "gtin": "00012345678905",
8
  "image_urls": ["https://example.com/images/knee-brace.jpg"]
9
}

Truemed classifies items asynchronously. You’ll receive a product_catalog_item_eligibility_updated webhook when classification is complete. Store that status in your system and use it to control where Truemed appears in your storefront.

Updating a product

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

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

Looking up a product

Call get_catalog_item to retrieve a product’s current eligibility status and details by SKU.

1
POST /api/v1/product_catalog/items/detail
2
{
3
  "sku": "ITEM-001"
4
}

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.

Bulk uploads

For initial catalog ingestion or large-scale updates, use the bulk upload tool 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 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.
2. Update on attribute changes. Call update_catalog_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 for every new product added to your store—ideally before the product goes live, so classification can complete before customers see it.