Updating your catalog: what wins when data conflicts
The rules TrueSpec applies when a new upload, an API push, and hand edits touch the same product — field locks, additive attributes, and how to run one source of truth.
Once a catalog is live, updates arrive from more than one direction: a refreshed spreadsheet, an automated API push from your ERP or PIM, and hand edits made by your team in the portal. TrueSpec's conflict rules are simple and deterministic — this page spells them out so you can design your workflow around them.
The core rules
- Re-imports update in place. Products are keyed on your SKU. A row whose SKU already exists updates that product; a new SKU creates a new product. Uploading the same file twice changes nothing the second time.
- Per field, the newest import wins — for the fields it carries.
If your upload has a
descriptioncolumn, it overwrites the stored description. Fields your file doesn't carry are left untouched. - Attributes merge additively. An import sets or updates the attribute keys it carries and never deletes keys it doesn't mention. (Removing an attribute is an explicit, deliberate operation — a hand edit in the portal, or a removal directive on the write API.)
- Hand edits are protected by field locks. When someone on your team changes a value in the portal editor, that specific field on that specific product is locked. Every later import — spreadsheet or API — skips locked fields and reports exactly what it skipped, so your curation is never silently overwritten by a bulk feed. Locks are per-field and releasable from the product page whenever you want the feed to own that field again.
Two edges to respect
- Category isn't "blank means keep." A row that arrives without a category clears the product's category — and a product without a category can't stay published. Carry the category on every row (or set one for the whole file at review time).
- Spreadsheet images replace spreadsheet images. Images that came in via an image-URL column are replaced as a set by your next upload's image column — that's how a refreshed catalog refreshes its photos. Images added any other way (portal upload, bulk uploader, the image API) are never touched by a spreadsheet import. Details in Product images and documents.
Spreadsheet vs. API: neither outranks the other
The portal upload and the write API feed the same import engine with the same rules above. There is no hidden priority between channels — whichever writes a field last, wins (locked fields excepted, which both channels respect).
That means authority is a workflow decision you make, not something the system decides for you. The pattern that works:
| Data | Let this own it |
|---|---|
| Product existence, SKUs, categories, structured specs | Your system of record (ERP/PIM) via scheduled API pushes — or your master spreadsheet, if you're not automated yet |
| Descriptions, curated images, display polish | Hand edits in the portal — the field locks make them stick |
| Pricing and live stock | Keep them in your commercial systems; TrueSpec carries product content, and your customers join it to their commercial data by SKU |
The one anti-pattern: pushing the same field through two channels on a schedule. Nothing breaks — the rules above stay deterministic — but the field ping-pongs to whichever ran last. Pick one owner per field and the question never comes up.
Every import tells you what it did
The import report (portal or API) lists created and updated products, row-level errors, any fields skipped because of locks, and — for drafts — exactly which required attributes are missing. If an import "didn't take," the report says why; nothing is ever silently dropped.
Questions this guide didn't answer? Get in touch — or browse the interactive API reference.