Learning PathModule

Images and Assets

Learn about the differences between Images and Assets and the scenarios where you should use either Images or Assets.

Ask about this Page
Copy for LLM
View as Markdown

After completing this page, you should be able to:

  • Choose when to use either Images or Assets to solve your media requirements.

  • Apply tag strategies to organize Assets for frontend consumption.

  • Use Asset Sources to deliver media in multiple formats and resolutions.

In digital commerce, visual appeal is everything. Online shoppers rely heavily on product images when making purchase decisions and depend on high-quality visuals to evaluate product details, compare options, and build trust in a brand.

Why do images matter in digital commerce?

  • Increase conversions: a well-optimized image can increase sales.
  • Reduce returns: clear product visuals help set accurate expectations, decreasing return rates.
  • Strengthen brand identity: consistent and high-quality imagery enhances brand recognition.
  • Boost engagement: interactive media keep customers engaged longer.
However, as digital commerce businesses expand their catalogs and sell across multiple markets, effectively managing media assets becomes a challenge. commercetools provides two options to manage images with your product catalog: Images and Assets.

The following sections clarify the differences between Images and Assets and the scenarios where you should use each option.

Images

Images are integrated with Product Variants.
  • Purpose: represent product visuals directly on product pages and listings.
  • Storage and delivery: uploaded images are stored on a Content Delivery Network (CDN), ensuring fast loading times globally.
  • Limitations: no sharing between Product Variants. Implement this logic in your application, if required.
  • External hosting: you can link to images hosted externally by providing their URLs.
You can add, update, and delete Images either via the Merchant Center on the Product Variant level or via the HTTP API.

Assets

Assets provide a more flexible approach for handling various types of media, beyond just product images.

  • Purpose: manage multiple types of media (such as images, videos, and PDFs) associated with Products, Categories, or other resources.
  • Flexibility:
    • Multiple sources: an Asset can have different formats and resolutions (for example, video encodings and image sizes).
    • Rich metadata: you can use name, description, and tags for organization and filtering purposes.
    • Custom Fields: store additional information specific to your needs.
  • Use cases:
    • Product manuals (PDFs)
    • Localized videos
    • Multiple image resolutions for different contexts
    • 360-degree product views
    • Various video encodings for compatibility
  • External hosting: you can add links to images hosted externally by providing their URLs.
For more information about Asset type definitions and fields, see the Assets API reference.

Key differences at a glance

FeatureImageAsset
PurposeProduct-specific visualsGeneral media management
File TypesImages onlyImages, videos, PDFs, and more
MetadataLimited (URL, label)Rich metadata (name, description, tags, and custom fields)
OrganizationTied to Product VariantsFlexible; can be linked to Product Variants and Categories
Source optionsSingle sourceMultiple sources for different formats, resolutions, and encodings
Use casesProduct displaysProduct manuals, localized content, 360° views, high-resolution downloads, and any scenario that requires diverse media with detailed metadata and flexible management

Choose between Images and Assets

While Images are suitable for basic product visuals, Assets are generally the preferred method to manage media content. The flexibility, rich metadata, and support for multiple file types make Assets a powerful tool for creating engaging and informative product experiences.

If you need to manage anything other than simple product images or if you require detailed metadata and flexible organization, Assets are the way to go.

Working with Assets

Assets are managed through update actions on Products, Categories, and other resources. The following sections show common patterns for organizing and delivering Assets effectively.

Add an Asset

To add an Asset to a Product Variant, use the addAsset update action. The following example adds a PDF product manual:
POST /{projectKey}/products/<product-id> with:
Add an Asset to a Product Variant
{
  "version": 1,
  "actions": [{
    "action": "addAsset",
    "variantId": 1,
    "asset": {
      "sources": [
        {
          "uri": "https://example.org/content/product-manual.pdf",
          "contentType": "application/pdf"
        }
      ],
      "name": { "en" : "Product Manual" },
      "description": { "en" : "The manual for my product." },
      "tags": ["manual", "pdf"]
    }
  }]
}
The name and description fields provide human-readable metadata. The tags and optional contentType on the source let your frontend decide how to display the Asset. For example, a product details page could search for all Assets tagged as manual and use the contentType to render a PDF viewer or a video player.

Use tags to organize Assets

Tags are free-form strings that your frontend can use to filter and select the right Asset from the assets array. The following patterns illustrate common use cases.

Tags for language-specific Assets

When a video or document is localized into multiple languages, add a language tag so the frontend can select the correct version based on the user's locale:

{
  "assets": [
    {
      "tags": ["video", "en"],
      ...
    }, {
      "tags": ["video", "de"],
      ...
    }, {
      "tags": ["video", "fr"],
      ...
    }
  ]
}

Tags for aspect ratios

When the same Asset exists in landscape and portrait versions, tags let the frontend pick the right layout for the device. For example, a desktop view shows the landscape version while a mobile device shows the portrait version:

{
  "assets": [
    {
      "tags": ["image", "primary", "landscape"],
      ...
    }, {
      "tags": ["image", "primary", "portrait"],
      ...
    }
  ]
}

Tags for 360-degree images

A 360-degree view consists of multiple images shot at incremental angles. Tags identify which Assets belong to the sequence and in what order:

{
  "assets": [
    {
      "tags": ["image"],
      ...
    }, {
      "tags": ["360-image", "deg=0"],
      ...
    }, {
      "tags": ["360-image", "deg=10"],
      ...
    }, {
      "tags": ["360-image", "deg=20"],
      ...
    }
  ]
}
The frontend filters for all Assets with the 360-image tag and sorts them by the degree value to assemble the interactive view.

Use Asset Sources for multiple formats

An AssetSource represents a single Asset in a specific format, for example, an image in a particular resolution or a video in a particular encoding. Each source can include a key, dimensions, and contentType so your frontend can select the optimal format.

Asset Sources for different resolutions

In this example, a product image is available as a thumbnail, a regular-resolution version, and a high-resolution zoom version:

Add an Asset with multiple sources
{
  "assetId": "<id>",
  "name": { "en" : "My Product Image" },
  "sources": [
    {
      "uri": "https://example.org/product-full.jpg",
      "dimensions": {"w": 600, "h": 400},
      "key": "full"
    },
    {
      "uri": "https://example.org/product-thumb.jpg",
      "dimensions": {"w": 90, "h": 60},
      "key": "thumb"
    },
    {
      "uri": "https://example.org/product-zoom.jpg",
      "dimensions": {"w": 3000, "h": 2000},
      "key": "zoom"
    }
  ]
}
The frontend can use the key to find a specific source (for example, "thumb") or compare dimensions to choose the best resolution for the current display. You can also use the dimensions field to generate the HTML srcset attribute for responsive images:
<img
  src="https://example.org/product-full.jpg"
  srcset="
    https://example.org/product-thumb.jpg   90w,
    https://example.org/product-full.jpg   600w,
    https://example.org/product-zoom.jpg  3000w
  "
/>

Asset Sources for different video encodings

When a product video is encoded in multiple formats (for example, MP4, WebM, and HTTP Live Streaming (HLS)), each encoding is stored as a separate source:

{
  "assetId": "<id>",
  "name": { "en": "My Product Video" },
  "sources": [
    {
      "uri": "https://example.org/product-video.mp4",
      "key": "mp4",
      "contentType": "video/mp4"
    },
    {
      "uri": "https://example.org/product-video.webm",
      "key": "webm",
      "contentType": "video/webm"
    },
    {
      "uri": "https://example.org/product-video.m3u8",
      "key": "hls",
      "contentType": "application/x-mpegURL"
    },
    {
      "uri": "https://example.org/product-video-thumb.jpg",
      "key": "thumb",
      "contentType": "image/jpeg"
    }
  ]
}
In HTML5, the <video> element supports multiple sources and the browser picks the most suitable one:
<video controls poster="https://example.org/product-video-thumb.jpg">
  <source src="https://example.org/product-video.mp4" type="video/mp4" />
  <source src="https://example.org/product-video.webm" type="video/webm" />
  <source
    src="https://example.org/product-video.m3u8"
    type="application/x-mpegURL"
  />
</video>

Product Tailoring

Product Tailoring lets you customize product information for different Stores, including overriding which Images and Assets are associated with a Product Variant. For details on uploading tailored images and managing tailored assets, see the Product Tailoring API reference.

Key takeaways

  • Images are CDN-hosted visuals tied to Product Variants. They are simple to set up but limited to image files with minimal metadata.
  • Assets support any media type (images, videos, PDFs) with rich metadata, tags, and multiple sources per Asset.
  • Use tags to organize Assets by language, aspect ratio, 360-degree sequences, or any custom classification your frontend needs.
  • Use Asset Sources to deliver the same Asset in multiple formats or resolutions, enabling responsive images (srcset) and adaptive video (<video> with multiple <source> elements).
  • Prefer Assets over Images when you need metadata, multi-format delivery, or non-image media.

Test your knowledge

Where to next?

Great job at finishing the Images and Assets module! That brings us to the end of the Model your product catalog learning path. If you haven't yet completed our other functional learning paths, we strongly recommend that you complete them next. Click one of the cards below to get started. Good luck!