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.

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);

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.