Media
Learn how the media library stores uploads in your own S3 bucket and attaches one file to products, variants, collections, categories, campaigns, users, and blocks.
The media library holds one record per file.
Uploads go to your own S3 bucket. Everything that shows an image — a product, a variant, a collection, a category, a campaign, a block — points at the library item through an attachment record instead of holding its own copy of the file.
That indirection is the whole design. One file can appear in a dozen places, and each of those places can caption it differently, without a second copy of the bytes existing anywhere.
Where it lives
Content → MediaFiles are stored in your bucket at:
media/<id>.<ext>Uploading images
- Open Content → Media and choose Upload media.
- On the Upload tab, drop a file in. On the URL tab, paste one direct image or video URL per line to import several at once.
- Add alt text, then save.
On the URL tab, invalid URLs are skipped and the rest are still imported. One bad line does not lose the batch.
What is accepted
Uploads are capped at 50 MB, and the accepted types are:
JPEG
PNG
GIF
WebP
MP4
WebM
QuickTimeEach admin account can upload 10 files an hour.
Why SVG is refused
SVG is refused deliberately. An SVG is executable markup, so an uploaded one served from your own domain would be a way to run scripts on your storefront.
The check is not on the file extension. The file's real bytes decide its type, not the type the browser reports, so a script renamed to .png is rejected.
Finding a file
Filters cover:
- Type — image or video
- Source — library or static
- Kind
The search box matches alt text and filename.
Static assets appear here too
The list also shows the design assets that ship in the storefront's public folder — backgrounds, icons, logos, illustrations.
They are filed under the Static source, and they cannot be deleted from the admin because they are part of the code.
Reusing images
A library item can be attached to any of these:
- Product
- Variant
- Collection
- Category
- Campaign
- User
- Block
Each attachment records its own:
- Position
- Primary flag
- Caption
- Alt override
The same file can only be attached to the same owner once.
The item's detail page lists every place it is attached, grouped by owner type, with the primary image marked. That list is how you find out what a file is doing before you touch it.
Alt text is the only field you can edit after upload
There is no replace-the-file action: the admin edits alt text and nothing else, so a new photo means a new upload and re-attaching it. Deleting a library item is permanent and removes the object from your S3 bucket.
Deciding what to do with a file
Attach the existing item when the same photo should appear somewhere else. Uploading it a second time gives you two records to keep in step.
Set an alt override or a caption on the attachment when one placement needs different wording. The library item's own alt text stays as it is.
Upload a new file when the picture itself changes. There is no replacing bytes in place.
Check the detail page before deleting. Deletion is permanent and it removes the object from your bucket, and the list of attachments is what tells you how many places are using it.
The question before you delete or re-upload is:
How many places is this file attached to, and am I certain the bytes should leave the bucket?