Documentation

Understand the Product Projections API

Elevate, May 20-22-2025, Miami Beach, Florida

Learn how the Product Projections API can help you to retrieve contextual and localized product data.

After completing this page, you should be able to:

  • Explain the purpose and key features of the Product Projections API, including its ability to retrieve contextual and localized product data for building effective product detail pages (PDP).

Effective PDPs are crucial for digital commerce success, especially for businesses aiming for a seamless, localized online experience.

Robust PDPs not only provide comprehensive product information using the Product Projection API, but also enhance user engagement and drive conversions.

By achieving proficiency in techniques for efficient data retrieval, precise localization, context-aware pricing, and performance optimization, you will be equipped to create PDPs that cater to diverse customer needs, improve SEO, and ultimately contribute to increased sales and customer satisfaction.

Case study: Zen Electron

Zen Electron, a leading Australian electronics retailer, operates two distinct brands on the same Project: Electronics High Tech and Zenith Living. They need to display a PDP capable of managing complex requirements: displaying brand-specific product assortments, retrieving different pricing structures per brand, and presenting localized product content tailored to regional nuances and brand voice.

This module will guide you through building such a PDP using the TypeScript SDK and the Product Projection API, and by the end of this module, you will be able to:

  • Retrieve context-aware product data: utilize the Product Projection API to fetch product details precisely tailored to the user's context, including brand-specific content (via Tailoring), localized information, and channel-specific attributes.
  • Query efficiently: implement robust product lookups while applying parameters for localization, store scope, specific price selection criteria, and inventory status.
  • Manage Inventory and variant display: handle variant display option based on inventory.
  • Optimize API interactions: discover options to get reference field data and design effective caching strategies.
  • Assemble an engaging PDP: integrate key UI components, including high-quality media galleries, variant selectors, rich descriptions, customer reviews, and related product carousels, to build a compelling user experience.

Understand the Product Projection API

The Product Projection API is designed to deliver optimized and contextualized product data, ready for use in storefronts, applications, or other channels. It provides a view of your product data tailored to specific needs, such as locale, currency, customer group, and store context. Here are its key aspects:

Current vs. staged Projections: live vs. draft data

Product data exists in two main states within Composable Commerce:

  • Current Projection: this represents the live, published version of the product that customers typically see.
    • Queries default to fetching this version (staged=false).
    • A current projection only exists after a product has been explicitly published.
  • Staged Projection: this represents the draft version of the product that contains unpublished changes.
    • Use the staged=true query parameter to retrieve this version.
    • Ideal for previewing changes internally before making them public.

Localized content handling

Products often contain content in multiple languages. The Composable Commerce API handles this efficiently:

  • LocalizedStrings: core product attributes like names, descriptions, and slugs are stored in a LocalizedStrings format, holding values for different locales.
  • Locale filtering: retrieve only the necessary translations using:
    • localeProjection: specify one or more specific locales (for example, en-US, de-DE).
    • storeProjection: automatically use the locales configured for a specific Store.
  • Automatic fallbacks: if a translation is missing for your requested primary locale, the API intelligently falls back to other configured locales (based on your project settings) to ensure essential fields like name are populated whenever possible.

Aggregated inventory availability

Get essential stock information directly within the product data:

  • Availability object: each Product Variant in the projection includes an availability object.
  • Eventually consistent: the availability object provides inventory information based on inventory entries associated with the variant's SKU. Note that this data is eventually consistent.

Store Projection

Using the storeProjection=<storeKey> parameter provides a powerful way to tailor the entire Product Projection based on a specific Store's configuration:
  • Automatic context application: filters and provides context across multiple fields.
  • Prices: filters prices to show only those relevant to the Store's distribution channels (plus any price without a channel).
  • Inventory: filters availability data to show only stock relevant to the Store's supply channels (plus any inventory without a channel).
  • Languages: automatically applies localeProjection based on the languages configured for the Store.
  • Product Tailoring: if the Product has tailored data defined for that Store, the tailored version is returned instead of the primary product data.
Using the storeProjection=\<storeKey\> parameter provides a powerful way to tailor the entire Product Projection based on a specific Store's configuration

Client Setup

Before you start making API calls to Composable Commerce, it's essential to establish a robust client that manages authentication, HTTP communication, and project scoping. This setup forms the backbone of your integration and ensures that every request is secure, correctly routed, and aligned with your project’s configuration.

For more details on how to set up and use the SDK in your own local environment, see the Prepare your work environment module in the Developer Essentials learning path.

Test your knowledge