Introduction

This document describes the Agentic Commerce Protocol - Product Feed implementation.

References

• OpenAI Documentation

• Guide - Agentic Commerce Protocol - Product Feed

• Cookbook - Agentic Commerce Protocol - Product Feed

Overview

The Agentic Commerce Protocol - Product Feed is a system for generating and transforming product feed data in JSON format, compliant with the Agentic Commerce Protocol - Product Feed standard by OpenAI. The system uses a modular, mapper-based architecture to transform internal product data into the required feed format.

Architecture

Core Components

Feed Marshaller (ChatGPTFeedMarshaller)

The ChatGPTFeedMarshaller orchestrates the entire feed generation process. It iterates through products and applies mappers sequentially, manages file I/O and JSON serialization with the Jackson ObjectMapper, and cleans up artifacts from previous runs before processing. It supports file splitting into multiple JSON files with configurable product limits and handles ZIP compression with configurable compression levels.

Mapper and Validator Provider (ChatGPTProvider)

The ChatGPTProvideris a factory pattern implementation for creating the following mapper instances:

• The ChatGPTProductMapper is responsible for basic product data mapping.

• The ChatGPTProductLinkMapper generates product detail page URLs that open in the PWA.

• The ChatGPTProductImageMapper generates valid product image links.

• The ChatGPTCommonDataMapper generates feed-level metadata, such as seller URL and name, and country information.

• The ChatGPTFeedValidator validates the JSON created. It is responsible for rejecting incomplete JSON data when the feed configuration requires it.

Mappers

Product Mapper (ChatGPTProductMapperImpl)

The ChatGPTProductMapperImpl maps the following core product attributes:

Configuration Options

All the configurations below are defined as properties in the syndication-target.properties file.

The configuration keys must start with intershop.syndication.target.ChatGPTProductFeed. and end with the key suffixes listed below:

Link Mapper (ChatGPTProductLinkMapperImpl)

The ChatGPTProductLinkMapperImpl generates PWA product detail page URLs using URL rewriting. It uses the same URL rewriting functionality that is used for generating the sitemap for the PWA3+ feed. As defined for the PWA3+, the URL includes product name, category path, and the category name and SKU as URL query parameter.

Image Mapper (ChatGPTProductImageMapper)

The ChatGPTProductImageMapper uses the image_url feed configuration for the image-view and image-type to select the product image for the primary product image. It also handles optional additional images by using the image-view and image-type configured for one or more additional_image_urls. If no view and type combination is configured for the additional_image_urls, the attribute is not included in the JSON.

It uses image type/view configurations stored as syndication custom attributes during the configuration in the feed UI.

Common Data Mapper (ChatGPTCommonDataMapperImpl)

This mapper applies feed-level attributes (required for all products in the feed).

Validator (ChatGPTFeedValidatorImpl)

The ChatGPTFeedValidatorImpl validates the mapped product data against OpenAI requirements. It checks mandatory attributes such as id, title, description, availability, image_url, price, etc. If the feed configuration to Include Only Complete Products is set to yes, it removes incomplete products from the JSON data file. Otherwise, all products—even incomplete ones—get written into the JSON files.

Data Models

Class Diagram

Description and JSON Mapping

ChatGPTProduct

This is the core product entity for the JSON serialization.

It has the following required attributes:

• id - maps to JSON item_id

• title

• description

• link - maps to JSON url

• imageLink - maps to JSON image_url

• availability

The optional attributes are:

• brand

• category - maps to JSON product_category

• price

• currency

• additionalImageLinks - maps to JSON additional_image_urls

The fixed data flags are:

• condition - by default, set to new

• enableSearch - maps to JSON is_eligible_search and defaults to true

• enableCheckout - maps to JSON is_eligible_checkout and defaults to false

ProductFeed

This is the container holding the products and feed metadata.

• products - The list of ChatGPTProduct objects

• storeCountry - A single country code that maps to JSON store_country

• targetCountries - A list of country codes that maps to JSON target_countries

• sellerName - The store name that maps to JSON seller_name

• sellerUrl - The store URL that maps to JSON seller_url

• returnPolicyPageUrl - The return policy page URL that maps to JSON return_policy

Availability

The options for availability have the following values: in_stock, out_of_stock, pre_order, backorder, and unknown. Only in_stock and out_of_stock are used. If the product is online, in_stock is used.

Processing Flow

1. Initialize the mappers and the validator with the provider.

2. Loop through each product in the iterator and check if a new JSON file is needed (based on maxNumberOfProductsPerJsonFile). Create a new ProductFeed object with the common data.

3. Use the mappers to map product data through the following pipeline:
   ProductMapper - Maps basic product attributes
   LinkMapper - Creates product URL
   ImageMapper - Creates image URLs
   Validator - Checks the quality of the data

4. Depending on the feed configuration, add (valid) products to the current feed.

5. Write the feed to a JSON file with pretty-printing.

6. If compression is enabled, the generated JSON files get compressed into ZIP archive and clean up afterwards.

Configuration

Syndication Parameters

The following table shows the configurations stored in the database table Syndication_AV:

Syndication Properties

These are configurations stored in properties, for example, in the syndication-targets.properties file.

The property keys must all start with: intershop.syndication.target.ChatGPTProductFeed.

Error Handling

The implementation handles missing or incomplete data, with fallbacks for some attributes.

Validation prevents incomplete products from affecting the feed, but can be circumvented in the UI if required.

The system logs warnings for file deletion and configuration parsing issues.

Extensibility

If required, new mappers can be added or replaced by replacing the ChatGPTProvider implementation.

There are configurations in the properties and the feed configuration that change the data written, reducing the need for code changes.

The modular design allows customization via syndication-targets.properties.