Why Everlyst doesn't trust Etsy's product_id alone for variation imports

Editing variations in a spreadsheet is one of the most useful things you can do with an Etsy catalog, and one of the easiest to get quietly wrong. The danger is never the edit itself. It is the moment you re-import the file and every row has to find its way back to the exact offering it came from.

Get that matching right and a variations CSV is a precise, powerful tool. Get it wrong and you have changed the price of the wrong size, zeroed the stock on the wrong color, or removed an option you meant to keep - and you may not notice until a customer does.

This post is about that matching problem, and why we made a deliberate choice not to solve it the obvious way.

The obvious approach, and why it bites

Etsy gives each variation a product_id. The tempting shortcut is to lean on it entirely: write the id in the export, read it back on import, match row to offering, done. It looks airtight.

It isn’t, and the reasons are not exotic. An id can be stale - the file on your desk was exported days ago, and the live shop has moved since. Ids can shift as Etsy regenerates a listing’s offerings under the hood when its variation structure changes. And an id tells you a record exists; it does not, on its own, confirm that the record is still the same offering you think you are editing.

For most data, a slightly stale lookup is harmless. For variations it is the opposite, because variation edits are destructive by nature. You are setting a price, setting a quantity, sometimes removing an offering. If the match is wrong, the edit is not just inaccurate - it actively damages the wrong part of your shop. A matching strategy that is “usually right” is not good enough when “occasionally wrong” means data loss.

A reference that rides along with the row

The first half of our answer is an internal Everlyst reference we call _evl_ref. Every variation export carries it as a hidden value on each row.

Its only job is to survive the trip. You can sort the file, filter it, paste a block of new values, hand it to a collaborator, rearrange the columns - all the ordinary things people do to spreadsheets that destroy row order. Through all of it, _evl_ref stays attached to its row. When the file comes back, that reference is how Everlyst reconnects each row to the exact variation it was exported from, regardless of where it ended up in the file.

This is the part that makes a spreadsheet safe to actually edit like a spreadsheet. Without a travelling reference, “row 5” means nothing after a sort. With one, a row knows what it is no matter how the sheet has been shuffled.

It is worth being clear about what _evl_ref is not. It is not a tidy column added for neatness, and it is not generic CSV plumbing. It is a safety device - the thing standing between “I edited the medium” and “I accidentally edited the small because the rows moved.”

Confirming the match, not just trusting it

A reference tells Everlyst which offering a row claims to be. The second half of the answer is refusing to take that claim on faith for anything destructive.

Before applying a destructive variation edit, Everlyst confirms the match against what the variation actually is - not just its id:

• an exact variant signature, so the offering’s combination of options has to line up with what is live;
• option identity, checking that the options themselves are the ones expected, not just similarly named;
• base-value checks against the current live state, so an edit aimed at one configuration cannot land on a different one that happens to share an id.

In this model, product_id is demoted to a hint. It can help confirm a match, but it is never the sole basis for one. If the signals disagree - the id points one way but the signature says otherwise - Everlyst does not force the edit through. It would rather decline a risky write than perform a wrong one.

The payoff: it touches only what you targeted

All of this adds up to a simple, boring, valuable promise: an edit changes the offerings you meant, and leaves the rest of your live products alone.

A change aimed at one set of variations cannot spill onto neighbors that happened to share an id. A stale sheet cannot talk Everlyst into rewriting something that has moved on since you exported. Offerings you never targeted are preserved, not collateral damage.

That is the difference between a tool that does what you meant and one that does what the row literally said. For variation editing, where the cost of “what the row literally said” is a wrong price or a wiped option, that difference is the entire reason to trust the workflow.

None of this removes the value of a safety net underneath. Even the most careful matching benefits from being reversible, which is why every bulk job still keeps a snapshot you can roll back - see Backup & Restore. For the workflow this safety machinery sits inside, read editing Etsy listings in a spreadsheet, and for what happens when your sheet and your live shop disagree - deletions, ghosts, and conflicts - see spreadsheet conflict handling. The fuller picture is on the features page.