Bulk Catalog Export

The Bulk Catalog Export pattern pulls Snappy’s catalog into your own data store asynchronously. You queue a job, poll until it completes, then download a compressed JSON file. This is the right pattern when you need a local copy of the catalog — for blending with other data sources, powering a search index, or serving from your own infrastructure.

When to use

Use bulk export when:

You already have local catalog infrastructure (search index, database, product schema)
You want to blend Snappy products with other sources
Your rendering layer cannot tolerate per-request API latency

Use Real-Time Catalog Access instead for simpler integrations that don’t need a local copy.

The three-phase lifecycle

Every export goes through Queue → Poll → Download:

Queue — POST to an export endpoint to start a job. You get back a job ID.
Poll — GET the job status until status is completed (or failed).
Download — fetch the file URL from the completed job response.

Two export paths

Filtered products export

Export products from the full catalog with optional filters.

POST /v3/products/exports

{
  "filter": {
    "collectionId": "col_abc123",
    "location": "US"
  }
}

Collection-scoped export

Export all products in a specific collection.

POST /v3/collections/exports

{
  "collectionId": "col_abc123",
  "location": "US"
}

Only 1 concurrent export job is allowed at a time, shared across all export types. Creating another export while a job is active returns 409 Conflict. Poll for completion before starting a new job.

Poll and download

Both export types share the same poll endpoint:

GET /v3/exports/{exportId}

async function waitForExport(exportId, { pollIntervalMs = 5000, timeoutMs = 300000 } = {}) {
  const start = Date.now();
  while (Date.now() - start < timeoutMs) {
    const res = await fetch(`${SNAPPY}/v3/exports/${exportId}`, { headers });
    const job = await res.json();
    if (job.status === "completed") return job;
    if (job.status === "failed") throw new Error(`Export failed: ${job.error}`);
    await new Promise(r => setTimeout(r, pollIntervalMs));
  }
  throw new Error("Export timed out");
}

async function downloadExport(job) {
  const res = await fetch(job.fileUrl); // pre-signed URL, no auth needed
  return res.json(); // { data: [Product, ...] }
}

// Full flow:
async function runExport(collectionId, location = "US") {
  const startRes = await fetch(`${SNAPPY}/v3/products/exports`, {
    method: "POST",
    headers,
    body: JSON.stringify({ filter: { collectionId, location } }),
  });
  const { id: exportId } = await startRes.json();
  const job = await waitForExport(exportId);
  return downloadExport(job);
}

import time, requests

def wait_for_export(export_id, poll_interval=5, timeout=300):
    start = time.time()
    while time.time() - start < timeout:
        res = requests.get(f"{SNAPPY}/v3/exports/{export_id}", headers=headers)
        job = res.json()
        if job["status"] == "completed":
            return job
        if job["status"] == "failed":
            raise RuntimeError(f"Export failed: {job.get('error')}")
        time.sleep(poll_interval)
    raise TimeoutError("Export timed out")

def download_export(job):
    res = requests.get(job["fileUrl"])  # pre-signed URL, no auth needed
    return res.json()

def run_export(collection_id, location="US"):
    start_res = requests.post(
        f"{SNAPPY}/v3/products/exports",
        headers=headers,
        json={"filter": {"collectionId": collection_id, "location": location}},
    )
    export_id = start_res.json()["id"]
    job = wait_for_export(export_id)
    return download_export(job)

Keeping your local copy fresh

After the initial bulk export, use the stock-availability-updates webhook to receive incremental updates instead of re-exporting the full catalog on a timer.

stock-availability-updates

Subscribe to this event in your Webhook configuration. Each event carries the products whose availability or pricing changed. Update only those records in your local store.

Re-run a full bulk export periodically (daily or weekly) as a safety net, and rely on webhooks for real-time freshness in between. This covers any webhook delivery failures.

Common pitfalls

Pitfall	Fix
Starting a second export before the first completes	Check for active jobs before queuing; handle `409 Conflict`
Polling too aggressively	Use 5-second intervals minimum; the export rarely completes in under 30 seconds
Ignoring the file URL expiry	Download the file immediately after the job completes; pre-signed URLs expire
Not subscribing to stock webhooks	Your local copy will drift; pair bulk export with `stock-availability-updates`

Real-Time Catalog Access — simpler alternative without local infrastructure
Swag Products Access — swag-specific catalog access

Introduction

Patterns

Recipes

Migration

When to use

The three-phase lifecycle

Two export paths

Filtered products export

Collection-scoped export

Poll and download

Keeping your local copy fresh

Common pitfalls

​When to use

​The three-phase lifecycle

​Two export paths

​Filtered products export

​Collection-scoped export

​Poll and download

​Keeping your local copy fresh

​Common pitfalls

​Related

When to use

The three-phase lifecycle

Two export paths

Filtered products export

Collection-scoped export

Poll and download

Keeping your local copy fresh

Common pitfalls

Related