Real-Time Catalog Access

The Real-Time Catalog Access pattern serves Snappy’s V3 catalog API on demand, with data fetched live from Snappy (and optionally cached at your edge). No local mirror, no nightly sync. Snappy is the source of truth.

When to use

Use real-time when:

You want live pricing and availability without sync lag
You don’t have local catalog infrastructure to maintain
You want the simplest possible integration path

Use Bulk Catalog Export instead when:

You already have a local catalog or search index you want to blend Snappy products into
You need offline access or want to blend with other data sources
Your rendering layer can’t tolerate API latency on every request

Two paths

Collection-based (recommended)

Fetch products scoped to a specific collection - the usual pattern for partners who have a dedicated collection for their program.

GET /v3/collections/{collectionId}/products

This endpoint uses cursor pagination. Follow links.next until it returns null.

async function fetchCollection(collectionId, { location = "US" } = {}) {
  const products = [];
  let cursor = null;
  do {
    const url = new URL(`${SNAPPY}/v3/collections/${collectionId}/products`);
    url.searchParams.set("location", location);      // ISO 3166-1 alpha-2, required
    url.searchParams.set("include", "brand,tags");
    url.searchParams.set("fields", "priceRange,variantsCount");
    url.searchParams.set("page[size]", "100");       // max 300
    if (cursor) url.searchParams.set("page[cursor]", cursor);
    const res = await fetch(url, { headers });
    if (!res.ok) throw new Error(`Snappy ${res.status}: ${await res.text()}`);
    const body = await res.json();
    products.push(...body.data);
    cursor = body.links?.next
      ? new URL(body.links.next).searchParams.get("page[cursor]")
      : null;
  } while (cursor);
  return products;
}

from urllib.parse import urlparse, parse_qs
import requests

def fetch_collection(collection_id, location="US"):
    products = []
    cursor = None
    while True:
        params = {
            "location": location,
            "include": "brand,tags",
            "fields": "priceRange,variantsCount",
            "page[size]": 100,
        }
        if cursor:
            params["page[cursor]"] = cursor
        res = requests.get(
            f"{SNAPPY}/v3/collections/{collection_id}/products",
            headers=headers, params=params,
        )
        res.raise_for_status()
        body = res.json()
        products.extend(body["data"])
        next_link = (body.get("links") or {}).get("next")
        if not next_link:
            break
        cursor = parse_qs(urlparse(next_link).query)["page[cursor]"][0]
    return products

Filter-based

Fetch from the full catalog with filters, without scoping to a collection.

GET /v3/products?filter[collectionId]=...&location=US

Useful when you want to merge multiple collections, apply tag or price filters globally, or access the catalog without a fixed collectionId.

Featured products

Featured products are a Snappy-curated selection of the most popular items in a collection that fit the recipient’s budget. We recommend displaying them at the top of your collection page, above the full product list.

GET /v3/collections/{collectionId}/products/featured?filter[price][gte]=70&filter[price][lte]=100

filter[price][gte] and filter[price][lte] are required - pass the recipient’s budget range.
The response is not paginated - one call returns the full featured selection in data (typically fewer than 100 products).
Pass a stable seed (for example, the recipient ID) so the same recipient sees the same featured products on every visit.
Request fields=selectedOrFirstAvailableVariant to get an orderable variant on each product without a separate variants call.

async function fetchFeatured(collectionId, { min, max, location = "US", seed } = {}) {
  const url = new URL(`${SNAPPY}/v3/collections/${collectionId}/products/featured`);
  url.searchParams.set("filter[price][gte]", min);
  url.searchParams.set("filter[price][lte]", max);
  url.searchParams.set("location", location);
  url.searchParams.set("include", "brand");
  url.searchParams.set("fields", "selectedOrFirstAvailableVariant,priceRange");
  if (seed) url.searchParams.set("seed", seed);
  const res = await fetch(url, { headers });
  if (!res.ok) throw new Error(`Snappy ${res.status}: ${await res.text()}`);
  const { data } = await res.json();
  return data;
}

import requests

def fetch_featured(collection_id, min_price, max_price, location="US", seed=None):
    params = {
        "filter[price][gte]": min_price,
        "filter[price][lte]": max_price,
        "location": location,
        "include": "brand",
        "fields": "selectedOrFirstAvailableVariant,priceRange",
    }
    if seed:
        params["seed"] = seed
    res = requests.get(
        f"{SNAPPY}/v3/collections/{collection_id}/products/featured",
        headers=headers, params=params,
    )
    res.raise_for_status()
    return res.json()["data"]

See Get featured collection products for the full parameter reference.

After picking a product

Once a user selects a product, fetch the full detail and its variants:

JavaScript

// Product detail (options matrix for variant pickers)
const product = await fetch(`${SNAPPY}/v3/products/${productId}?fields=options,priceRange,variantsCount&include=brand,tags`, { headers }).then(r => r.json());

// Orderable variants
const { data: variants } = await fetch(`${SNAPPY}/v3/products/${productId}/variants?fields=price`, { headers }).then(r => r.json());

The product detail endpoint returns the object directly (no data wrapper). The variants endpoint returns { data, links } with page-number pagination.

Resolve the selected variant at checkout

JavaScript

// `selection` maps option name → chosen value, e.g. { color: "black", size: "l" }
function resolveVariant(variants, selection) {
  return variants.find((v) =>
    Object.entries(selection).every(
      ([level, value]) => v.selectedOptions[level] === value
    )
  );
}
const variant = resolveVariant(variants, { color: "black", size: "l" });
// variant.id goes into POST /v3/orders

Pre-select each option’s firstSelectableVariant on page load to avoid dead-end combinations.

Caching guidance

Fetching live on every render is fine for most traffic levels. Add a short cache at your edge if you need to reduce latency or API call volume:

Data	Recommended TTL
Product list (collection)	5–15 minutes
Product detail + variants	5–15 minutes
Product tags	1 hour
Availability (`GET /v3/variants/{variantId}/availability`)	Recommended: subscribe to `stock-availability-updates` webhooks for display state, and call this endpoint only immediately before placing an order.

Cache by (collectionId, location, page[cursor]) for list pages, by (collectionId, location, filter[price][gte], filter[price][lte], seed) for featured products, and by (productId, location) for detail pages.

Common pitfalls

Pitfall	Fix
Serving stale out-of-stock products	Subscribe to `stock-availability-updates` webhooks to keep your local availability state current. Call `GET /v3/variants/{variantId}/availability` only immediately before checkout - not on every page render.
Calling availability on every UI render	This will exhaust your rate limit on busy catalog pages. Use webhooks for display state; reserve the availability endpoint for the pre-order check.
Missing `location` param	Always pass `location` (ISO 3166-1 alpha-2) - it affects availability and pricing
Not using `filter[...]` params to narrow results	Fetching the full catalog when only a subset is needed wastes bandwidth, forces extra pagination, and burns your rate limit. Narrow server-side with `filter[price][gte]` / `filter[price][lte]`, `filter[tagId]`, `filter[brandId]`, `filter[search]`, `filter[catalog]`, etc.
Rendering a product with no selectable variant	Pre-select `firstSelectableVariant`; never show a picker with no valid default
Exceeding rate limits on page load	Cache aggressively, batch requests, use `page[size]=300` to minimize pages

Bulk Catalog Export - for local catalog infrastructure
Place Orders - the next step after catalog browsing
Build a Rewards Experience - end-to-end recipe using this pattern

Introduction

Patterns

Recipes

Migration

When to use

Two paths

Collection-based (recommended)

Filter-based

Featured products

After picking a product

Resolve the selected variant at checkout

Caching guidance

Common pitfalls

​When to use

​Two paths

​Collection-based (recommended)

​Filter-based

​Featured products

​After picking a product

​Resolve the selected variant at checkout

​Caching guidance

​Common pitfalls

​Related

When to use

Two paths

Collection-based (recommended)

Filter-based

Featured products

After picking a product

Resolve the selected variant at checkout

Caching guidance

Common pitfalls

Related