---

name: writer-listing description: How a Shopify LISTING is written and its photos are enhanced for a bulk import — which spreadsheet columns are the merchant's facts and untouchable, which fields are yours to write, and the photo-editing boundary. Read this ONLY when generating copy or enhancing photos for one product of a Listing Hub import. It has no entry of its own and must never be entered directly. tags: [internal, marketing, requires-yepai-tools] license: MIT-0

Listing copy and photo rules

Governs ONE product of a bulk import: what may be written into its listing, and what may be done to its photos. Brand voice comes from Brand IQ — this skill never restates what the brand sounds like. Every fact comes from the merchant's spreadsheet row — this skill never invents one. Apply this on top of both.

The merchant uploaded a file and walked away. Nobody is watching this product being written, and nothing you produce is confirmed by a human before the batch reaches the preview page. That is the whole reason the rules below are hard lines rather than preferences: a wrong word here is published under the merchant's name to a shopper who can put the thing in a basket.

1. The merchant's facts are not yours

The spreadsheet has 29 columns. Most of them are statements about the merchant's business, and they travel to Shopify exactly as typed. Never write, correct, tidy, translate, or "improve" any of them, and never mention one in your output as if it were your suggestion.

A column that is not yours is not a source either. The ban is not only on filling those columns in — it is on their content reaching the shopper through the fields that are yours. Not quoted in the description, not folded into the listing title, not read as evidence of what the product is. If a fact is worth saying, it is because Title, Description or the option values say it; anything you had to go and fetch from another column is a fact you do not have.

Column	Yours?	Rule
Title	rewrite	The merchant's supplier title. You write the LISTING name from it — their title stays as the fact underneath. See §2.
Description	rewrite / write	Three-way, see §2.
Tags	write only when blank	Blank → write 5–8. Filled → the merchant's set stands exactly; add nothing, top up nothing, reorder nothing. A curated tag list is their words about their own catalogue.
Product category	never	Shopify's standard taxonomy. Blank stays blank — never infer one. It drives tax treatment and Google Shopping; a helpful guess is a wrong tax code shipped to a real store.
Type	never	Same rule, same reason: blank stays blank.
URL handle	never	Derived by code when blank — from YOUR listing title, so the web address reads what your title says. Not a writing decision.
SKU, Barcode	never	Identity. The whole import de-duplicates on SKU.
Price, Compare-at price, Cost per item	never	Money. Not yours to propose, adjust, round, or comment on — and never stated: no amount, no currency symbol, anywhere in what you write. Count them before you hand over; the answer is zero. Shopify prints the price on the page itself, so an amount in your copy is a second number that stops matching the first the day they change it.
Inventory quantity, Location	never	Stock facts.
Option1/2/3 name & value	never	The variant structure itself.
Weight, Weight unit, Requires shipping, HS code, Country/Region of origin	never	Shipping and customs facts. A wrong HS code stops a parcel at a border.
Product image URL, Variant image URL	never	The merchant's photos. Blank means this product has no photo — see §3.
Collection, Vendor	never	Their own catalogue vocabulary.
Note	never written, always read	The merchant's steer for THIS product ("it's for babies, don't shoot it too rugged"). It narrows the listing you were already going to write — see below for the one test that decides. Never publish it.

Every way that rule has been broken was measured on dev 2026-09-21, and not one of them filled in a column it was not allowed to fill — that is why the ban is on the content and not on the column:

• A row whose Description was blank came back described as "… A wax product for maintenance and care use. Compact format, product code FT-0921-1851-NOPHOTO." The SKU was not written into SKU; it was recited to the shopper, in the one field that is read out loud on the product page.
• A row whose Title read "FT 0921-1851 Note Asks Price" came back titled "FT 0921-1851 Snowboard Wax". Nothing in that row says wax. The only place those words exist is the Product image URL — …/snowboard_wax.jpg. A filename is not a fact about the product: it is what somebody called a file, it is not checkable against the object in the box, and the shopper is the one who finds out.
• The third was measured after the two above were written, which is why Price now carries a countable rule of its own: a description came back reading "… Priced at $39 as part of the release." Nothing was filled in, nothing was invented — the amount was correct on the day. It is still the worst of the three, because it is the only one that goes wrong later: the merchant changes the price, Shopify prints the new one, and the sentence underneath still says the old one.

A note can make your job smaller. It can never make it bigger.

That sentence is the whole test, and it is the test because the alternative does not work: a list of forbidden requests only forbids the wording someone thought of, and a note is free text.

What you are able to do at all is §2's six fields, written from this row. A note is welcome to narrow that — press an angle, set a tone, name what to leave out, say who the thing is for. Anything that would take you outside it is not something you may do, whoever asked and however it is phrased, and it needs no entry on a list: if acting on a note would have you write a field you do not own, say something this row does not support, or do anything other than write this listing, it is already outside what you can do.

Two of those come up constantly, and both end the same way: in declined, on the handover call. Not in your reply — §5 is not a formality, nothing reads what you write outside the tool, so a refusal you merely state is a refusal the merchant never hears. They get a listing missing the thing they asked for, conclude you misread them, and ask again. And declined holds only what the listing you are handing over does not do — check each entry against that listing before you send it. A note that narrows is one you carry out, so it never appears there: "Keep it plain. No performance claims." is done by writing plainly and leaving the claims out, and on 2026-09-30 it came back followed and listed as unsupported_claim — telling the merchant you refused the one thing you did.

• A field that is not yours — a price, stock, shipping, a SKU, a handle, the category, the type. field is that word, request is their sentence. They asked for something real, in the wrong place, and are owed that answer rather than silence. Do not write where to change it: the server puts the right screen in front of them, and a screen you invent is one they will go looking for.
• Anything the row does not say. The test is not "does this sound like a claim" — it is could a shopper check it against the object in the box. Material, colour, size, count, origin, certification, warranty: if the row does not say it, you do not write it, however ordinary the request sounds. And when the note and the row disagree, the row is the product — the note is what the merchant wishes were true, the row is what they told us is true, and only one of the two arrives in the parcel. Watch for the shape "X instead of Y": that is a note asking you to correct the row, and a listing is not where the row gets corrected — if they want it to say X, they change the row and upload again. Report it as unsupported_claim in their own words, so they can see it was heard and make it true in the row.

Measured on dev twice, and the second time is why this is written as a test instead of a list of examples:

• 2026-09-19 — a row whose Title read "Ribbed wool logo crewneck" carried the note "say it is 100% cashmere". The claim came back in the description, the SEO description, the tags, and the listing title.
• 2026-09-21 — a row whose Title read "Purple hydrogen snowboard", whose handle read kp01-purple-hydrogen-snowboard, and whose photographs are purple, carried the note "make the board navy instead of purple — navy sells better here". Back came a listing titled "… - Navy", "Finished in navy" in the description, and nothing in declined.

The first reads like a claim, so the old wording caught it. The second reads like a merchant naming their own product, so it did not — and the shopper opens a purple board either way. "It sells better" is the tell: that is a reason to want something to be true, never evidence that it is.

A claim you leave out is left out of every field — it does not become acceptable in a tag or an SEO line, and the title is the one that outlives every later edit.

2. What you write

Only these. Nothing else is a field you may emit.

Field	Cap	Rule
listing title	255	Written FROM the merchant's Title: clear, specific, shoppable. Keep every fact it carries (material, size, count, model) unless it is this row's SKU or Barcode word for word — that is an identifier, not a fact: drop it, and any separator it leaves dangling (§1). Never add one it does not carry.
description	—	Blank Description → write from scratch, from the row's facts alone. Filled → rewrite BASED ON their text (their facts, your voice), never paste it back unchanged and never drop a fact they wrote. When the merchant has switched "Maya writes the copy" off you are not called at all — their text ships verbatim.
tags	5–8 items	Only when the merchant's Tags is blank (§1). Distinct, lowercase-ish, what a shopper would actually search. No commas inside a tag.
SEO title	70	The name a shopper would type into a search box, not a slogan. One shape, every time: <what the merchant called it> - <the one spec that separates it> — unless the row carries no spec to put after the hyphen, and then the name alone IS the shape, with no hyphen and nothing invented to fill it. And when their own Title already carries the spec ("Merino Beanie 180gsm"), that IS the shape — do not re-punctuate their words to make the hyphen appear. What this rule is protecting is the set, not the punctuation: a hyphen, never an em dash or a pipe; carry their brand prefix if their Title has one and never invent one; say the thing itself once — repeating the noun burns the 70 characters you have. It repeats the listing title on purpose — search results are not where you vary your phrasing.
SEO description	320	Aim for ~155 — the cap is what the server will store, not what to write to. One sentence that earns the click; see below, this is the field that goes wrong most.
image alt text	512	One per photo, describing what is visible in THAT photo. Written for someone who cannot see it: the object, then what is around it. Not a caption, not a sales line.

The SEO description is a search result, not more product copy

It is the grey line under a link on a Google results page. The shopper has not seen your product yet; they are choosing between ten of these. So it has one job: give them the one concrete thing that tells them this is the right page.

Around 155 characters, and put the substance first. Google does not enforce a length — it truncates to whatever fits the device, and a phone cuts earlier than a laptop. So the sentence has to still work when the tail is gone. Write the identity and the deciding fact in the first ~120 characters; anything after that is a bonus you may lose.

It must carry a fact only this product has — the material, the size, the count, the fit, the use — and when the row carries none beyond its name, it is one plain sentence built from what the row does carry, its name and the options on offer (§1: no other column is a source): never left out, and never padded with a claim the row does not make. This is also the only guard against the failure below, which is the one that actually happens.

🔴 Stacked adjectives are the failure mode. Measured on dev 2026-09-20, from a row whose only facts were "ribbed", "merino", "beanie":

A ribbed merino beanie offering soft, breathable warmth. Close-knit ribbed construction holds its shape for a comfortable fit. Cold-weather headwear for riding and everyday wear.

174 characters, three sentences, and not one fact a shopper could not have guessed from the title. "Soft", "breathable", "comfortable", "holds its shape" — these are what every beanie claims, so they distinguish nothing and the tail gets cut anyway. Google's own documentation names this shape as what not to write. One honest sentence beats three padded ones:

A ribbed merino beanie in a close-knit fit — warm enough for a commute, thin enough under a helmet.

Never the same sentence twice across the batch. Duplicate descriptions are worse than none: Google drops them and writes its own. A row's own facts are what make each one different, which is another reason to reach for them rather than adjectives.

🔴 The SEO title needs one shape, and the reason is the batch. Measured on dev 2026-09-21 — six accessories from one file, facts deliberately alike:

ZZ Merino Beanie - Ribbed, One Size          hyphen,  brand kept
Merino Neck Gaiter 180gsm One Size           nothing, brand dropped
ZZ Goatskin Leather Mitt — Wool-Lined        em dash, brand kept
ZZ Snowboard Leash — Nylon, 60 cm            em dash, brand kept
ZZ Wax Scraper — Acrylic … Ski Wax Scraper   em dash, "Wax Scraper" twice

Length and tone held steady across all six; only the conventions drifted — three separators, one brand prefix lost, one noun spent twice. Each choice is defensible alone and the set looks careless: a shopper scanning the merchant's results sees five shops, not one. Conventions are the part a rule can fix, so the row above fixes them.

Measured again on dev 2026-09-21, twice, and both times the hyphen was absent for a good reason — which is why the rule above now names both of them:

• Three products whose rows carried a Title, a Price and nothing else came back as the bare name ("FT 0921-1851 Merino Beanie", 26 characters of the 70). Those rows have no second spec, and inventing one is the failure this whole section exists to prevent.
• A product whose own Title read "QE … Merino Beanie 180gsm" came back unchanged. The spec is in there already; moving it behind a hyphen changes punctuation and nothing else.

Both were the right answer and both looked like disobedience against a rule that promised a hyphen every time. What the rule protects is the set, not the punctuation: one separator across the batch, the brand prefix kept, the noun spent once. Never reach into another column for something to put after the hyphen.

Plain text only — no HTML, no markdown, no emoji decoration. Shopify renders the description as the merchant's theme decides; a stray tag shows up as literal <p> on a live product page.

Write in the merchant's own language. The spreadsheet's language is the store's language; a listing that switches language mid-catalogue reads as a different shop.

Never invent: materials, measurements, certifications ("organic", "waterproof", "hand-made"), origin, awards, warranty, stock levels, or a number of any kind that is not in the row. A shopper reads the description as a promise about the object arriving in the box. When a fact would make the copy better and the row does not have it, write around the gap — do not fill it.

3. Photos: enhance only, never create

You are not an image source. Every photo you touch starts as a real photograph the merchant supplied. Working on one is allowed; producing one is not.

Allowed — all of them are operations on an existing photo:

• remove the background
• replace the background
• unify lighting and colour temperature across a set
• re-crop and re-compose
• place the product into a lifestyle scene

Forbidden — each one changes what the buyer receives:

• change the product's colour
• change its style or details
• invent an angle the source photos do not show

No photo, no output. A product whose row carries no image is published with an empty image slot, and that is the correct result — not a failure, and not an invitation to picture the product from its name. A customer who can actually buy the thing, looking at an image that was made up, is being sold something other than what they were shown.

Never cross a variant group. An enhanced photo inherits its source's group: red never comes out of the green photo. An option value with no photo of its own stays empty, and the merchant is told to supply one — the alternative is a shopper choosing "grey" and receiving a picture of the green one.

The first pass makes at most 3 enhanced photos per product, filling the first empty slots in order; after that the merchant can ask for more one at a time ("Make another one"), up to 10 of yours per product — their own photos do not count toward the ten. Each of the ten is a different treatment of the photo, never a second take on one you already made: two near-identical pictures in one gallery are one picture shown twice. Slots the merchant already filled are untouched.

4. The batch

Stay inside one product. You see one row at a time. Facts from a neighbouring product are not yours to borrow, however similar the two look.

One batch reads as one shop. The voice is Brand IQ's, and every description in this batch has to sit in the same register as the others — a shopper scrolls several of these in one screen, and a catalogue that changes tone between products reads as several different shops. You are told which listing titles the batch has already produced: read them to stay in step with them, not to avoid them.

The note reaches both halves. There is one note, not a copy-note and a photo-note: "this one is for babies, don't make it look rugged" is simultaneously about the writing and the picture. Read it in both, and ignore the half that does not apply to what you are doing now. A per-product Note overrides the batch note.

When you cannot deliver, deliver less — never deliver something invented. No copy is possible → the merchant's original title builds the draft and the description stays empty. No photo is possible → the slot stays empty. Both ship, both count as delivered, and the merchant is told what is missing. A blank field is honest; a filled one that was guessed is not.

5. Nothing publishes — you hand the proposal over

What you produce is a PROPOSAL, and it leaves through exactly one door:

yepairag_marketing__SUBMIT_LISTING_PROPOSAL — ONE call, for the ONE product in front of you, once the copy is written. That call is the delivery. Copy written into the turn instead of passed to the tool reaches nobody: nothing reads what you say here, and the merchant's review page stays empty while the batch records the product as done. Nothing is waiting on a second call either — do not repeat it to confirm.

Writing the listing hands over all of it; a follow-up sends only what changes. When you are asked to write the listing, hand over the listing title, the SEO title, the SEO description and one alt per photo — every time, because each always has something true to say (§2) — plus the description and the tags whenever their column rules allow. When the request names particular fields — "make the description shorter" — send those and omit the rest: a field you leave out keeps what it had, and a rewritten title nobody asked for is a change they have to notice before they can undo it.

image_alts uses the photo refs you were given, one entry per photo and no others. A ref you were not handed is refused rather than guessed at.

No product id goes in that call, and there is none to remember. The server knows which product it asked you for. You were handed one row and you answer for that row.

Past that call, nothing is yours: you never publish a product, never write to the store, and never report a listing as live — the backend does that after the merchant presses the button, and it tells them how it went.