{"title":"Upload images, media, and other files","slug":"uploading-media","url":"https://support.storeconnect.com/articles/uploading-media","url_markdown":"https://support.storeconnect.com/articles/uploading-media.md","subtitle":null,"summary":"Upload images, videos, documents, and other files via the media manager or product records: accepted formats, size limits, file naming conventions, URL-based imports, and troubleshooting failed imports, retry counts, and broken storefront images.","type":"Help_Documentation","video_url":"","keywords":"import url, cdn, cloudinary, retry count, media import, broken images, dropbox, google drive","last_modified":"2026-08-21T07:12:35+0000","body_markdown":"StoreConnect includes a media manager for organizing and managing the images and files you need for products and on your website. In the background, we store and deliver all media through **Cloudinary**, a CDN (Content Delivery Network). This topic explains how to upload and use media via the media manager, how to update product images, and manage image volume limits in accordance with your plan.\n\n## Manage media in folders\n\nDepending on how you want to manage your files over time, you might want to create individual folders to organize media. For example, to separate product images, web images, marketing assets, documents, etc. The media manager displays up to 250 folders. See [manage media and images](organize-files-and-media).\n\n## Requirements for media\n\n| File type                         | Accepted formats                                                                                  | Notes                                                                                                                                                                                                                                       | Size limit (Regular plans) | Size limit (Emporium and Flagship) |\n|-----------------------------------|---------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------|------------------------------------|\n| Image                             | Recommended: jpg, png, webp, gif, tif, tiff, psd, wdp. Accepted vector and other: eps, ai, svg, bmp, ico, jp2 | Products: Minimum 640px width or height, (Recommended) 1024px - 2048px or above.Use same aspect ratio for all product imagesOther images: Banner minimum width 1920pxOut of the box aspect ratio:640px (page embed)1024px (opened in modal) | 5MB                        | 20MB                               |\n| Video and audio                   | Video: mp4, mov, webm, avi, flv, wmv, mpg, mpeg, ogv, 3gp. Audio: mp3, aac, flac, m4a, wav, ogg   | Audio files are processed as the video resource type                                                                                                                                                                                        | 100MB                      | 500MB                              |\n| Document                          | pdf                                                                                               | Standard print formats recommended                                                                                                                                                                                                          | 10MB                       | 20MB                               |\n| File                              | Any non-executable file type                                                                      | Use for downloads and attachments that are not images, video, audio, or PDFs                                                                                                                                                                | 10MB                       | 20MB                               |\n| URL reference (for any file type) | Standard URL                                                                                      |                                                                                                                                                                                                                                             |                            |                                    |\n\n## Upload media to StoreConnect\n\n1.  In the **All Media** window, go to the folder you want to add the file to.\n2.  Select **Add media**.\n\n    ![Add media dialog](https://res.cloudinary.com/hzkr6fi81/image/upload/v1771815913/knowledge/media/AddmediaNew_zedrxp.png)\n\n3.  Choose the **File type** and enter a **Name** for the file.\n4.  To upload files from your computer, browse for or drag the files to the **Add media** window.\n5.  To add files via URL:\n    1.  Select **Import media from URL**.\n    2.  Enter the URL in the **Import Url** field. Note that the URL must be publicly accessible. Files behind authentication or restricted access will not import successfully.\n6.  Complete any additional fields, including advanced options.\n7.  Select **Save media**.\n\nThe file appears in the selected folder in the media manager, with a thumbnail preview once processing completes.\n\nTo bulk upload media, see [Import media files in bulk](import-media-files-in-bulk).\n\n## Add media to a product record\n\nUploading or changing images within products automatically maps them and updates them in the media manager. \n\n### Copy the media file URL\n\n1.  In the media manager, locate the file you want to link to.\n2.  Click the menu icon (three dots) and select **Copy link**.\n3.  Use the URL to reference the image.\n\n### Update media to a product record\n\n1.  Navigate to the product record.\n2.  Upload via the media manager:\n    1.  In the **Product Actions** section, select **Add media**.\n\n        ![Media upload in product](https://res.cloudinary.com/hzkr6fi81/image/upload/v1771816120/knowledge/media/ProductActions_a2s01a.png)\n\n    2.  Follow the on-screen prompts to upload or reference images.\n    3.  **Save media**.\n3.  Upload via the product key relationships:\n    1.  Go to the **Media used by this product** section.\n\n        ![Media upload by related list in product](https://res.cloudinary.com/hzkr6fi81/image/upload/v1771816119/knowledge/media/OldStleUpload_eid6rx.png)\n\n    2.  Select **New**.\n    3.  Complete the form to add media.\n4.  **Save**.\n\nThe product record shows the newly added file.\n\n## Add and manage where media is used in your content\n\nThe media manager enables you to quickly see and manage where an image or file is used in your content. \n\n### View and add where media is used\n\n1.  Open the media record in the media manager.\n2.  Scroll to the bottom of the record. \n3.  Click to open each object type where media is used.\n\n    ![Content using this media](https://res.cloudinary.com/hzkr6fi81/image/upload/v1771806282/knowledge/media/ContentUsingMedia_kwm6hf.png)\n\n4.  Click **New** to add this media to the relevant object. The native Salesforce window opens.\n5.  Follow the prompts to add and then **Save**.\n\n## File name conventions for media\n\nWe encourage you to use a consistent convention for naming media so that files can be easy recognized and updated in the future. For example, you might align a product image with a product code or category in your system. However, stick with the conventions that work best for your business and product types.\n\n**Example for a product**\n\nA lounge suite with the style name Monty that comes in 4 colors, in 2S (2 seater), for which you want to upload 4 different photo angles:\n\nLounge\\_Monty\\_Aqua\\_2S\\_front, Lounge\\_Monty\\_Aqua\\_2S\\_side, Lounge\\_Monty\\_Aqua\\_2S\\_styled\n\n**Example for a web page**\n\nImages for blogs:\n\nPage\\_blog\\_hero, Blog\\_\\[blogname\\]\\_hero\n\n## Change image sizes\n\nWhen you upload images, they are stored in the original size, but you can download different sized images when you know how: See [Insert media using Liquid](liquid-how-to-insert-media), specifically the section on rendering images in various sizes. If you upload images that are smaller than the size to be rendered, image quality can be impacted.\n\n---\n\n## About CDN and media storage\n\nStoreConnect's media manager work on Cloudinary, a CDN (Content Delivery Network). A CDN is a global network of servers that delivers files from the location closest to each visitor, so images and media load quickly for customers regardless of where they are in the world.\n\nWhen you upload a file or import one via URL, StoreConnect processes it through Cloudinary and generates a CDN URL that is stored on the media record. This is the URL you reference to display the image on your site. \n\n## CDN bandwidth limits\n\nEach StoreConnect plan includes a monthly CDN bandwidth allocation. Bandwidth is the volume of data transferred when your store delivers media (images, videos, and documents) to visitors via the CDN.\n\n| Plan     | Included CDN bandwidth per month |\n|----------|----------------------------------|\n| Boutique | 10 GB                            |\n| Emporium | 100 GB                           |\n| Flagship | 400 GB                           |\n\nThese are soft limits, and store functionality is generally not immediately impacted if you exceed the monthly allocation. StoreConnect monitors bandwidth usage and will contact you if your store consistently exceeds the plan allocation. \n\n:::warning\nIf usage continues beyond the limit, your media may become unavailable to storefront visitors. If this happens, we recommend purchasing a CDN upgrade for your plan. See the [StoreConnect pricing page](https://storeconnect.com/pricing) for details.\n:::\n\n## Tips for staying within file size and bandwidth limits\n\nKeeping file sizes small reduces both the likelihood of hitting upload limits and the bandwidth consumed every time a file is delivered to a visitor.\n\n**Compress images before uploading**\n\nUse a compression tool before uploading images to StoreConnect. Free options include [Squoosh](https://squoosh.app), [TinyPNG](https://tinypng.com), and [ImageOptim](https://imageoptim.com) (Mac). Aim to reduce file size as much as possible without visible quality loss.\n\n**Resize images to their display size**\n\nUpload images at the size they will actually display, not at the original camera or export resolution. A banner image displayed at 1920px wide does not need to be uploaded at 4000px or more. Larger dimensions mean larger files and more bandwidth per page load.\n\n**Use WebP format for web images**\n\nWebP produces significantly smaller files than JPG or PNG at comparable quality and is accepted by StoreConnect. Where your image editing tools support it, export in WebP for any image used on the storefront.\n\n**Host videos externally where possible**\n\nVideo files are large and consume bandwidth quickly. Where possible, host videos on YouTube or Vimeo and embed them in your content rather than uploading them directly to StoreConnect. Reserve direct uploads for cases where an external host is not suitable.\n\n**Use appropriately sized images in Liquid templates**\n\nCloudinary can serve images at different sizes via URL transformations. When referencing images in Liquid templates, request the size that matches the display context rather than always loading the full original. See [How to insert media using Liquid](liquid-how-to-insert-media) for details on rendering images at specific sizes.\n\n## How media import works\n\nWhen you add media using an Import URL, StoreConnect processes it through the following pipeline:\n\n1.  You populate the **Import Url** field on the [media record](media-object-reference) with a publicly accessible URL pointing to the source file. For example, a direct link to a file hosted on Dropbox, Google Drive, your own web server, or another CDN.\n2.  The **Url** field must be blank. If it already contains a value, the import job skips the record.\n3.  A scheduled background job detects the record and attempts to download the file from the Import URL and upload it to the CDN (Cloudinary).\n4.  On success, the **Url** field is populated with the generated CDN URL and the image displays on the storefront.\n5.  On failure, the **Retry Count** field is incremented. The job retries up to 5 times. After 5 failed attempts, no further automatic retries occur and manual intervention is required.\n\n:::note\nThe import job runs on a schedule. After saving a media record, allow a few minutes for the CDN URL to appear in the **Url** field.\n:::\n\n![Media record showing the Import Url, Url, and Retry Count fields](https://res.cloudinary.com/hzkr6fi81/image/upload/v1781677766/documentation-media/uploading-media/Media_Upload.jpg)\n\n## Troubleshoot media import and CDN issues\n\nThis section covers common issues where a media record fails to generate a CDN URL after using the Import URL method, or where images appear broken on the storefront.\n\n### The Url field is blank after setting an Import URL\n\nIf the **Url** field has not been populated after setting an Import URL, work through the following checklist:\n\n1.  Is the **Url** field already populated? If it contains any value, the import job skips the record. Clear the **Url** field and save.\n2.  Is the Import URL publicly accessible? Open it in an incognito or private browser window. If it requires a login, shows a landing page, or returns an error, the URL is not accessible to the import job.\n3.  Has **Retry Count** reached its limit? Check the **Retry Count** field on the media record. If it shows `5`, the import has failed the maximum number of times. See [Retry count has reached 5 and no CDN URL was generated](#retry-count-has-reached-5-and-no-cdn-url-was-generated).\n4.  Has enough time passed? The import job runs on a schedule. Wait a few minutes after saving before investigating further.\n5.  Are StoreConnect sync triggers enabled? If triggers have been disabled (for example, during a package upgrade), the import job does not run. See [StoreConnect sync triggers](storeconnect-sync-triggers) to check and re-enable them.\n\nIf none of the above apply, review the remaining sections below for more specific causes.\n\n### The Url field already has a value but the wrong image displays\n\n**Cause:** The **Url** field is already populated with a CDN URL, so the import job skips this record, even if the current URL points to an outdated or incorrect image.\n\n**Resolution:**\n\n1.  Open the media record in Salesforce.\n2.  Clear the **Url** field so it is blank.\n3.  Confirm the **Import Url** field contains the correct source URL for the new image.\n4.  Save the record.\n5.  Wait a few minutes for the import job to generate a new CDN URL.\n\n### Retry count has reached 5 and no CDN URL was generated\n\n**Cause:** The import job attempted to download and upload the file 5 times and failed each time. Common reasons include an inaccessible URL, a URL pointing to a sharing page instead of a direct file, or a file type mismatch. After 5 failures, no further automatic retries occur.\n\n![Media record with Retry Count showing 5 and a blank Url field](https://res.cloudinary.com/hzkr6fi81/image/upload/v1781677767/documentation-media/uploading-media/Media_Upload_2.jpg)\n\n**Resolution:**\n\n1.  Identify and fix the underlying cause first. Review the sections below to determine why the import is failing.\n2.  Once the cause is resolved, open the media record and set the **Retry Count** field back to `0`.\n3.  Confirm the **Url** field is blank.\n4.  Save the record. The import job will pick it up on the next scheduled run.\n\n### Older versions: retry count shown in the Import Url field\n\nOn older versions of StoreConnect, there is no dedicated **Retry Count** field. Instead, the retry count is stored as a tag prepended to the **Import Url** value, for example:\n\n`[retry:5]https://yoururl.com/image.jpg`\n\nThis tag is added automatically by StoreConnect, so you do not need to add it manually. Once `[retry:5]` appears, the import job stops retrying the record.\n\nTo reset and allow the import to try again:\n\n1.  Fix the underlying cause of the failure first.\n2.  Edit the **Import Url** field and remove the `[retry:5]` prefix, leaving only the URL.\n3.  Confirm the **Url** field is blank.\n4.  Save the record.\n\n\n### Import URL is not publicly accessible\n\n**Cause:** The URL in the **Import Url** field requires authentication, is behind a login wall, or is otherwise restricted. The import job cannot access URLs that are not publicly available. This commonly occurs with:\n\n-   Dropbox links that require sign-in, have restricted sharing settings, or contain session parameters.\n-   Google Drive files that are not shared with \"Anyone with the link.\"\n-   URLs on internal networks, intranets, or password-protected sites.\n\n**Resolution:**\n\n1.  Copy the Import URL and open it in an **incognito or private browser window** (not a browser where you are already logged in).\n2.  If the URL requires a login, shows a permission error, or redirects to a sign-in page, it is not publicly accessible.\n3.  Update the sharing settings on the source file to allow public access, or host the file at a publicly accessible URL.\n\n:::tip\n**Dropbox:** Ensure the link sharing is set to \"Anyone with the link.\" Copy the sharing link, then:\n- Change `dl=0` to `dl=1` at the end of the URL to force a direct download instead of the preview page.\n- Remove any `st=...` parameter from the URL. This is a session token tied to your Dropbox login that the import job cannot use.\n- Example: `https://www.dropbox.com/scl/fi/abc123/image.jpg?rlkey=xyz\u0026dl=1`\n\n**Google Drive:** Set the file sharing to \"Anyone with the link\" and use the direct download format: `https://drive.google.com/uc?export=download\u0026id=FILE_ID` where FILE_ID is the identifier from the original sharing URL. See [▶️ Prepare Google Drive URLs for bulk import](prepare-google-drive-urls-for-bulk-import) for a step-by-step walkthrough.\n\n**Other services:** Any URL containing session tokens, expiry parameters, or authentication tokens will fail, because the import job has no way to authenticate. Always test the URL in an incognito window before using it as an Import URL.\n:::\n\n### Source URL points to a sharing page instead of a direct file\n\n**Cause:** The Import URL resolves to an HTML preview or sharing page rather than the actual file. For example, a Dropbox link with `dl=0` opens a preview page with download buttons, or a Google Drive link opens the file viewer. The import job needs a URL that returns the raw file content, not an HTML page.\n\n**Resolution:**\n\n1.  Open the Import URL in a browser. If you see a web page with the file embedded (rather than the file downloading directly), the URL is not a direct file link.\n2.  Convert the URL to a direct download link:\n    -   **Dropbox:** Change `dl=0` to `dl=1`, or replace `www.dropbox.com` with `dl.dropboxusercontent.com` in the URL. Remove any `st=...` session parameters.\n    -   **Google Drive:** Use the format `https://drive.google.com/uc?export=download\u0026id=FILE_ID`.\n    -   **Other services:** Look for a \"direct link\", \"raw file\", or \"download link\" option rather than the standard sharing URL.\n3.  Update the **Import Url** field on the media record with the direct link.\n4.  If **Retry Count** shows `5`, reset it to `0`.\n5.  Clear the **Url** field if it contains a value, and save.\n\n### Import URL was truncated because it exceeds 255 characters\n\n**Cause:** The **Import Url** field is limited to 255 characters. If the source URL is longer than 255 characters, it is silently truncated when saved, resulting in a broken URL that cannot be resolved by the import job.\n\n**Resolution:**\n\n1.  Check whether the Import URL in the media record matches the full source URL. If it appears cut off, the URL has been truncated.\n2.  Shorten the URL by removing unnecessary query parameters, or use a URL shortening service.\n3.  Alternatively, download the file and re-upload it directly through the media manager rather than using the Import URL method.\n\n### Images appear broken on the storefront but the media record looks correct\n\n**Cause:** The media record has a populated **Url** field and appears correct in Salesforce, but the image does not display on the storefront. This can occur when:\n\n-   The CDN URL was generated but the file was not correctly scoped to your organization’s folder in Cloudinary.\n-   The CDN URL is malformed or points to a resource that no longer exists.\n-   The required CSP (Content Security Policy) trusted URLs have not been added. See [Troubleshoot images and media](troubleshoot-images-and-media) for CSP setup instructions.\n\n**Resolution:**\n\n1.  Open the **Url** field value in a browser. If the image does not load, the CDN URL is broken.\n2.  Clear the **Url** field, confirm the **Import Url** is correct, reset **Retry Count** to `0` if needed, and save. This forces a fresh import.\n3.  If the issue persists after re-importing, contact StoreConnect support. CDN scoping issues may require intervention from the operations team.\n\n:::note\nWhen resetting a failed import, check both the **Retry Count** field (set it to `0` if it shows `5`) and the **Import Url** field (remove any `[retry:5]` prefix if present). Both can block the import job from running again.\n:::\n\n### Website shows a stale or outdated image after re-importing media\n\n**Cause:** After re-importing media, the storefront continues to display the old image. This is typically caused by browser caching or CDN edge caching serving the previous version of the file.\n\n**Resolution:**\n\n1.  Perform a hard refresh in your browser: **Ctrl+Shift+R** (Windows/Linux) or **Cmd+Shift+R** (Mac).\n2.  If the old image still appears, clear your browser cache or test in an incognito/private window.\n3.  If the correct image appears in incognito but not in your regular browser, the issue is local browser cache. Clear your cache or wait for it to expire.\n4.  If the old image persists even in incognito, the CDN cache may not have updated yet. CDN caches can take up to 24 hours to fully refresh. If the image remains stale beyond this period, contact StoreConnect support to request a cache invalidation.\n\n### File type mismatch prevents successful upload\n\n**Cause:** The **File Type** picklist value on the media record (image, video, document, file, or url) does not match the actual content of the file at the Import URL. For example, the File Type is set to \"image\" but the URL points to a PDF document.\n\n**Resolution:**\n\n1.  Open the media record in Salesforce.\n2.  Verify the **File Type** matches the actual file. Check the file extension in the Import URL or open the URL in a browser to confirm the file type.\n3.  Correct the **File Type** picklist value.\n4.  If **Retry Count** has reached `5`, reset it to `0`.\n5.  Clear the **Url** field if it contains a value, and save.\n\n### Advanced: bulk re-import CDN URLs for multiple media records\n\n:::warning\nThis is an advanced operation intended for Salesforce administrators. The script below clears the **Url** field on all media records that have an existing URL, which forces a complete re-import from the **Import Url** field. Always run this in a sandbox environment first and verify results before executing in production.\n:::\n\nIn some situations you may need to regenerate CDN URLs across many media records at once, for example after a sandbox refresh or a CDN migration. The following Apex script can be executed in the Salesforce Developer Console (Setup \u003e Developer Console \u003e Debug \u003e Open Execute Anonymous Window):\n\n```apex\n\nList\u003cs_c__Media__c\u003e newMedias = new List\u003cs_c__Media__c\u003e();\nList\u003cs_c__Media__c\u003e existingMedias = [\n    SELECT Id, s_c__Import_Url__c, s_c__Url__c\n    FROM s_c__Media__c\n];\nfor (s_c__Media__c media : existingMedias) {\n    if (String.isBlank(media.s_c__Url__c)) { continue; }\n    media.s_c__Import_Url__c = media.s_c__Url__c;\n    media.s_c__Url__c = null;\n    newMedias.add(media);\n}\nupdate newMedias;\n```\n\nThis script:\n\n1.  Queries all media records in the org.\n2.  For each record that has an existing **Url** value, copies the current **Url** into the **Import Url** field and clears the **Url** field.\n3.  Updates all affected records. The scheduled import job will then process each record and generate fresh CDN URLs.\n\nAfter running the script, allow time for the import job to process all records. The time required depends on the number of media records in your org."}