Add & manage product images

The Images tab on a product holds its photo gallery. You can add images three ways — upload a file from your device, paste an image URL, or supply a base64 data URI — then drag them into order and pick which one is the primary image. The primary image is the thumbnail that represents the product everywhere else in SKU: the products list, order lines, and packing slips.

This guide covers adding, reordering, setting the primary image, and deleting images, plus the edge cases around unreachable URLs and how files are stored on the server.

Before you begin

• You need the products.update permission. Without it the Images tab is read-only — the Upload from Device, Add from URL, drag-to-reorder, set-primary, and delete controls are all hidden, and you see the gallery only. See Product permissions reference.
• Open the product from the products list and select the Images tab. The tab is part of the product detail page.

Add an image

Upload a file from your device

1. On the Images tab, click Upload from Device (or drag image files onto the gallery / the Add image drop zone).
2. Pick one or more image files. You can select several at once — each is uploaded in turn.
3. The files are stored on SKU's server and appear in the gallery.

The uploaded file must be a real image — its MIME type has to start with image/. A non-image file (a PDF, a text file renamed to .jpg) is rejected by validation with "The uploaded file must be an image" rather than failing deep in image processing.

If the gallery was empty, the first image you upload automatically becomes the primary image. A product with no images shows an Add image drop zone when you can edit it, or a plain No images placeholder when the tab is read-only.

Add from a URL

1. Click Add from URL to open the URL import panel.
2. Paste an image URL (for example https://example.com/photo.jpg). Click Add Another to queue more URLs.
3. For each URL, choose how SKU should treat it:
   • Keep as Remote — SKU stores the external URL as-is and serves the image straight from that remote host. Nothing is copied to SKU's server.
   • Fetch & Store — SKU downloads the image now and stores a local copy, then serves it from SKU. Use this when the source host is unreliable or may change.
4. Click Import.

Base64 data URIs

The same image field also accepts a base64 data URI (a string beginning with data:image/...;base64,). SKU decodes it and stores it as a local file, exactly like an upload. This is mainly used by integrations and imports rather than typed in by hand.

What happens when a URL can't be reached

When you add a Keep as Remote URL, SKU tries to fetch the image to confirm it resolves. If the fetch fails, the image is not rejected — the row is still created with the raw URL you supplied, but it's flagged as unresolvable (its resolvable field is set to false) and you get a warning, not an error.

The warning wording depends on whether the image was being set as primary:

Image role	Warning message
Primary (main) image	The main image url: <url> failed to resolve
Any other image	The image url: <url> failed to resolve

Because the record is saved anyway, an unreachable image shows up later as a broken image. Products that have one are flagged on the products list — apply the Has Broken Image filter (under the Other filter group) to list them. To find and repair these across the whole catalog, see Find & fix broken product images. Note that a Fetch & Store URL that can't be downloaded is treated the same way — the raw URL is stored and flagged, not silently dropped.

Reorder images and set the primary

The gallery is drag-and-drop. Grab an image by its drag handle and move it; the new order saves automatically.

The first image in the gallery is always the primary image — it carries the Primary badge and spans a larger tile. So there are two ways to change which image is primary:

• Drag an image to the front of the gallery, or
• Hover a non-primary image and click its star (Set as primary) — SKU moves it to the front and marks it primary.

Setting a new primary image has two automatic effects:

1. Siblings are un-set. Marking one image is_primary = true resets every other image on that product to is_primary = false, so exactly one image is ever primary. This is enforced whenever an image is saved — there is no database constraint doing it, so always change the primary through the Images tab rather than editing rows directly.
2. Packing slips are re-queued. Changing the primary image re-queues packing-slip reprints for that product's open sales orders that already have fulfillments, so the picking paperwork shows the current image. This happens in the background.

If you delete images until only one remains, SKU automatically promotes that last image to primary.

Delete an image

Hover the image in the gallery and click the trash icon. The image is removed immediately.

Deleting an image also cleans up storage: if the image is a locally stored file (uploaded, fetched, or from a data URI), SKU deletes the underlying file and its thumbnail from the server. If the image is an external Keep as Remote URL, only the database row is removed — SKU never had a local copy to delete, and it doesn't touch the remote host.

Image fields reference

Each gallery image is a record with the following fields. You mostly interact with them through the tab, but they explain the behaviour above.

Field	Meaning
url	The image location. For locally stored images this is a bare on-disk key that SKU rewrites to a full tenant asset URL when serving. For Keep as Remote images it's the external URL, passed through unchanged.
relative_url	The raw stored value of url before any rewriting — the bare disk key or the untouched external URL.
is_external	Derived, not stored: true when url has a URL scheme (that is, it's a remote address), false for a local disk key. Drives whether delete touches server storage.
resolvable	Whether the last resolve check succeeded. Set to false for an unreachable URL.
is_primary	Whether this is the product's primary image. Only one per product; setting it un-sets the others.
sort_order	Gallery position; updated as you drag.
name	Optional label.
image_checked_at	When the image was last checked for reachability (used by broken-image detection).

An image is unique per product by its url — you can't add the same URL to the same product twice.

Storing and deleting images on the server directly

Alongside the gallery, SKU exposes two standalone actions used by other parts of the app (for example rich-text editors and imports) to manage server-stored images independently of any single product:

• Store image on server — accepts a file, URL, or base64 string, always downloads and stores it locally, and returns the stored tenant asset URL. If the source can't be resolved, it returns an error rather than a warning.
• Delete image from server — deletes a locally stored image (and its thumbnail) by its path. It only ever deletes a file that lives under your own uploads, and it does nothing for external URLs. Paths that try to escape the images storage area are rejected.

These operate on files on the server, not on a product's image rows, so use the Images tab for anything attached to a product.

Next steps

• Find & fix broken product images — locate and repair unresolvable images across the catalog.
• Edit a product's details — update the rest of the product alongside its images.
• Product detail page reference — everything on the product detail page, tab by tab.
• Publishing images to sales channels is covered in the Listings guide (coming soon).

Video transcript

The Images tab holds a product's photo gallery. Add images three ways — upload files from your device, drop them onto the gallery, or paste an image URL. The first image you add becomes the primary — the thumbnail that represents the product across SKU. Add from URL opens a panel where you paste one or more image links. For each, choose Keep as Remote to serve it from its host, or Fetch and Store to download a local copy. Once images are in the gallery, drag them into order and pick which one is primary.