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

# Caching Best Practices

The recommended path for most integrations is real-time product discovery via the `/search` endpoint. The guidance below is for use cases where product IDs are stored and revisited later, such as persisted carts, "saved for later" collections, or hand-curated shopping experiences.

## Cache IDs, not data

Product IDs and category slugs are stable identifiers — cache them freely and for as long as you like. Everything else on a product object (prices, availability, images, descriptions, offers, variants) should be treated as unstable.

**Do:**

* Store `product.id` from search results and reuse it later

**Don't:**

* Cache prices, availability, or offer URLs and serve them to users without refreshing
* Assume image URLs or product descriptions are permanent
* Cache offer URLs — these are short-lived and must be fetched fresh before presenting to users

## Refresh at load time

When you need to display a product to a user, fetch the latest data with `GET /v1/products/{product_id}` rather than relying on a cached snapshot.

**`TypeScript`**

```typescript title="TypeScript"
import { Channel3 } from "@channel3/sdk";

const client = new Channel3();

// At search time — cache the IDs
const results = await client.products.search({ query: "running shoes" });
const productIds = results.products.map((p) => p.id);
// store productIds in your database or session

// At display time — fetch fresh data
const product = await client.products.retrieve(productId);
```

**`Python`**

```python title="Python"
from channel3_sdk import Channel3

client = Channel3()

# At search time — cache the IDs
results = client.products.search(query="running shoes")
product_ids = [p.id for p in results.products]
# store product_ids in your database or session

# At display time — fetch fresh data
product = client.products.retrieve(product_id)
```

## Short-lived caches are fine

Caches with a short TTL (a few minutes to a few hours) on full product objects for presentational data (images, title) is reasonable. Just avoid caching product data for many hours or days.

| Data                                         | Cache strategy                         |
| -------------------------------------------- | -------------------------------------- |
| Product IDs, category slugs                  | Cache indefinitely                     |
| Product details (title, description, images) | Short TTL or refresh on display        |
| Prices, availability, offers                 | Always refresh before showing to users |