Consuming catalogs: a sync guide for dealers, ERPs, and storefronts

Reading the unified feed with one key, syncing deltas with updated_since and ETags, reconciling removals, and mapping your item numbers to vendor products.

One API key reads everything you've been granted — every vendor who has approved your access, merged into a single normalized feed. This guide covers the integration patterns that make a consumer-side sync robust. The interactive API reference is at truespec.net/docs.

The basics

• Authenticate with Authorization: Bearer <key>. Keys are read-scoped and owned by your organization.
• List endpoints (/v1/products, /v1/categories, /v1/brands) use cursor pagination — follow the cursor until it's exhausted; never assume page counts.
• You only ever see what your grants allow. When a new vendor approves you, their products simply appear in the same feed on your next sync — no integration change.

Sync deltas, not full catalogs

Every list endpoint supports updated_since, and responses carry ETag / Last-Modified headers. The standard loop:

1. Record a high-water timestamp when a sync finishes.
2. Next run, request /v1/products?updated_since=<that timestamp> and page through the changes.
3. Overlap the cursor by a minute or two (ask for slightly older than your high-water mark). Timestamps commit with real-world skew; the overlap costs a few duplicate rows — which your upsert ignores — and guarantees you never miss a write that landed mid-sync.

A 5–15 minute polling interval is plenty for catalog data; conditional requests (If-None-Match) make empty polls nearly free.

Reconcile removals periodically

Delta sync tells you about changes; it cannot tell you about disappearances. When a product is withdrawn — archived by the vendor, or a grant ends — it stops appearing in list results rather than emitting a change event. A mirror built on deltas alone will accumulate stale rows.

The fix is cheap: run a periodic full reconcile (nightly works well) — page through the full feed, and anything in your mirror that no longer appears has been withdrawn. Delta polls keep you current; the reconcile keeps you honest.

Mapping your item numbers to vendor products

Your ERP has its own item numbers. TrueSpec maintains a cross-reference so you can resolve them directly:

GET /v1/products/by-consumer-sku/{your-item-number}

returns the product (with headers reporting the match basis and confidence). Build the mapping by uploading your item file — item number, vendor part number, barcode/GTIN — in the portal's enrichment area; TrueSpec matches it against everything you've been granted, by GTIN first, then vendor SKU. Matching happens when the file loads (an unmatched item won't start resolving on its own), so re-upload the file when you add items or a vendor publishes new products you carry.

Two notes: match your own item file conservatively (an ambiguous item is left unmatched rather than guessed), and treat a 404 from by-consumer-sku as "not mapped yet," not "doesn't exist" — the product may simply be newer than your last mapping load.

Build against the contract

Endpoints under /v1/ are a permanent contract: changes are additive, breaking changes would ship under a new version path, and product identifiers are stable forever. Ignore JSON fields you don't recognize — new ones appear over time — and you'll never be broken by a TrueSpec release.

Questions this guide didn't answer? Get in touch — or browse the interactive API reference.