Skip to main content
A listing’s gallery holds up to 8 images, in the order you give them. There are two ways to fill it, and each replaces the gallery whole — so a shorter list is how an image is removed.
The road for anything that already hosts its images: a PIM, an ERP, a shop.
One call instead of nine, and sending the same URLs again costs nothing: we hash the set we already hold and do not re-fetch an unchanged one. That makes it safe to send your whole record on every sync, which is what a sync wants to do.The fetching is queued, so the listing is saved immediately and the images follow. A client reading it back straight away sees the old gallery, which is the honest answer: the new one does not exist yet.
A body carrying both fields is refused with 422. Each replaces the gallery whole, so sending both is asking for two different galleries.
include=images gives you the files themselves, each with the sizes we render:
Picking a variant saves fetching a whole photograph to show a thumbnail, which on a phone is the difference that matters.
hero is a banner crop, 1920 wide by 384 tall. It is for the top of a page and is not a product photo — a watch does not survive being cut to a fifth of its height.
The squares are squares because a grid of watches wants every cell the same shape. url is the only one that keeps the original proportions, and it is whatever the seller uploaded — sometimes 2,500 pixels of it, so it is the wrong thing to put in a list.

Adding one photograph

Upload the new file, then send imageHandles with the handle of every image the listing already has plus the new one, in the order the gallery should be in:
The images you name again are kept as they are, id and all; only the new one is attached. Nothing is uploaded twice. A handle can be named again only when it is on one of this business’s own listings (the one you are editing, or one it was copied from); a handle already attached anywhere else — another business’s listing, a message — is refused with 422. Upload the file again instead.

Reordering without re-uploading

The gallery becomes exactly these, in this order. An image left out is removed — deleted, not detached: a file that belongs to nothing is one we keep paying to store and nobody can reach. Only images already on one of this business’s own listings can be named here. An upload id from another business’s listing, or from a message, is refused with 422 (pointer /data/{index}), and a listing a Connect feed maintains answers 409 feed_managed.