Jobs to automate

AI Listings

Before you send instructions, keywords or tags. What the AI sees, what it writes, what it never checks.

Max Murray Updated on Oct 18, 2026

In short

Our AI writes each listing from the artwork itself, the file name and your keywords. It never sees the product name, the SKU, the prices or the sizes, so anything it must know goes in keywords or instructions.
It writes a title of comma-separated search phrases, a description, 13 tags and a short product name, in English, and fills some Etsy attributes if the template asks it to. Lengths and most rules come from the seller’s template.
You steer it per request or per image with three fields on POST /api-bulk-list: keywords (facts it can’t see), instructions (how to write the title, description and tags) and tags (terms guaranteed a slot).
Regenerating redoes the whole listing and costs credits again. Only the seller can trigger it, from the Listing Hub.
It does not check trademarks, brand names or Etsy’s banned words. The seller’s review before listing is the only check.

Before you start

This page is about steering the writing. How to create drafts, what they cost and how to follow them is on List Artwork. Everything here applies to drafts made through the API and to drafts the seller uploads, because both use the same template and the same AI.

What the AI sees

The artwork image, not the mockups. It is told the listing is a physical printed poster (never a digital download unless your instructions say so), to describe only what it can see, and to leave out hype and filler.
The file name. Through the API that is the last part of image_url, so https://example.com/fern-botanical-sage.png tells it more than https://example.com/img_0412.png.
Your keywords for that image, up to 300 characters. These are the same thing as the “AI hints” on a card in the Listing Hub.
From the template: the Etsy category, the Default Tags (it writes different ones), the AI Content Settings, which attributes to auto-fill, and the seller’s Etsy shop sections.

It does not see name (that is only the product name), the SKU, prices, sizes, the template’s Footer Text or the mockups. A subject, place, artist, collection or style the title should mention has to be in keywords or instructions.

What it writes

Field	Length	Rules
Title	Short 45–60, Medium 85–100, Long 120–140 characters (set by the template; Medium is recommended)	comma-separated search phrases; a title that runs long is cut at a comma; the Etsy limit is 140
Description	Short about 240 characters (1–2 sentences), Medium about 650, Long about 1,000	Medium and Long are 2–3 paragraphs; the template’s Footer Text is added underneath
Tags	always 13, each 20 characters or fewer	filled in this order: your API `tags`, then the template’s Default Tags, then the AI’s own; repeats removed; letters, numbers, spaces, hyphens and apostrophes only
Short product name	3–7 words	returned as `short_title`; used only as the SEO title in the Shopify CSV
Attributes	—	only if the template has AI Auto-fill Attributes ticked; see below

Everything is in English. Spelling is British when the template’s shop currency is GBP, AUD, NZD or CAD, and American for any other currency.
Accented letters become plain letters (é becomes e) in titles, descriptions, footers and tags.
Image alt text on Etsy and in the Shopify CSV is the listing title; there is no separate alt text.
With auto-fill on, it picks Primary and Secondary Colour, Style, Occasion, Holiday, Subject (up to 3, Digital Prints category only), Room (up to 5) and a Shop Section (only when the draft has none), leaving anything it is unsure of empty. A template default for Occasion, Holiday or Room overrides it. It never chooses the Etsy category, orientation, framing, pieces included, craft type, materials, aspect ratio or sustainability; those come from the template.
GET /api-bulk-list returns the title, short_title, description and tags, but not the attributes; the seller sees those in the Listing Hub.

Three ways to steer it

All three go on POST /api-bulk-list. keywords is per image. instructions and tags can be set for the whole request or per image; a per-image value replaces the request-level one for that image. They apply on top of the template and survive regenerating.

{
  "template_id": "3f6c1e2a-...",
  "tags": ["vintage botanical prints", "cottagecore wall art"],
  "instructions": {
    "title": "Start the title with the plant name, then the style, then the room.",
    "description": "Mention that the illustration is reproduced from a 19th-century plate. Do not mention frames."
  },
  "items": [
    {
      "image_url": "https://example.com/fern-botanical-sage.png",
      "sku": "FERN-001",
      "name": "Fern Botanical Print",
      "keywords": "fern frond, vintage botanical illustration, sage green on cream, bathroom and kitchen wall art",
      "instructions": { "tags": "Include the tag botanical bathroom art." }
    }
  ]
}

keywords (max 300 characters per image) are facts: what the picture is of, where, the style, the colours, the intended room. The AI treats them as hints about the artwork, so this is where the subject of an abstract or ambiguous image goes, and the name of a place, a plant or a breed it would otherwise have to guess.

instructions (max 2,000 characters each for title, description and tags) are how to write. Use the request-level ones for a batch-wide format and per-image ones for exceptions. How they combine with our own rules depends on the template’s mode: in Easy mode your instructions are added to our rules; in Custom mode they replace our rules for that field, though the title length limit still applies. You can read which mode a template uses from mode in GET /api-get-templates. Don’t tell it the product is a digital download unless it is.

tags (up to 13 per request or per image, 20 characters each) are terms you want guaranteed. They take the first slots, then the template’s Default Tags, then the AI fills what is left. If your tags and the Default Tags fill all 13, the AI writes none, so leave it room unless you mean to control every tag.

Regenerating

Regenerating redoes the whole listing; single fields can’t be regenerated. It replaces the title, tags and description (any description edits are lost and the current footer is added), moves a Ready draft back to Review, and costs credits again.
It keeps the AI hints and your API keywords, tags and instructions, and any Subject, Room or Shop Section already set.
The template’s AI settings are read fresh at every generation. A change to the template applies to the next generation, not to listings already written.
There is no API call to regenerate. The seller does it from the Listing Hub; to get different output from your side, change keywords or instructions and ask them to regenerate, or send the image again as a new draft with a new SKU.

When a generation fails

A failed generation is not charged, and a credit already taken comes back. The draft shows the reason in generation.error.
The usual reasons: an unreadable, corrupt or empty image (re-export it and send it again), a file missing from storage (the seller deletes the card and uploads again), or the template not loading (the credit is refunded; the seller clicks Generate again).
If only the attribute auto-fill fails, the listing still finishes and is charged, just without auto-filled attributes.

What it never checks

The AI does not check for trademarks, brand names, other people’s characters or Etsy’s banned words, and it has no way to know whether the seller holds the rights to the artwork. The Listing Hub grades the title, description and tags with fixed checks (lengths, tag count), not with AI. Everything can be edited before listing: the title (up to 140 characters), description, the 13 tags, attributes, shop section and materials. That review, by the seller, is the only check before a listing goes live, and the rights rules are on Rules.

Rules and limits

keywords max 300 characters per image; each of instructions.title, instructions.description and instructions.tags max 2,000 characters; up to 13 tags of 20 characters.
Titles max 140 characters; tags are letters, numbers, spaces, hyphens and apostrophes.
Listings are written in English only, with the spelling set by the shop currency.
Credits: 1 per draft, 2 when the template has 7 or more mockup scenes; every regeneration costs the same again (see List Artwork).
The AI only writes listings and reads imported order items. It does not generate, extend or upscale images, and there is no AI chat in the app.