SEO Rich Data - installation and configuration
Module purpose
The Kowal_SeoRichData module adds schema.org structured data to Magento 2 in JSON-LD format. Generated data can include products, offers, prices, availability, ratings, reviews, breadcrumbs, organization data, site name, search box, social profiles, FAQ, and video.
The module configuration is available in the Magento admin panel:
Stores > Configuration > Kowal > SEO Rich Data
Requirements
- Magento 2.
- Access to Magento CLI.
- Access to the Composer repository with the
kowal/module-seo-rich-data package. - Required base package:
kowal/base. - Permissions to run
bin/magento commands.
Installation via Composer
- Add the package repository:
You will receive Composer repository access details, meaning the customer email address and license token, by email after purchase. They are also available in the customer panel after logging in at kowal.store. Replace TWOJ_EMAIL_KLIENTA with your account email address and TWOJ_TOKEN with the token you received. Run the commands in the Magento root directory.
composer config repositories.kowal composer https://repo.kowal.store
- 2. Configure access credentials for the Kowal Composer repository:
composer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'
composer require kowal/module-seo-rich-data
php bin/magento module:enable Kowal_SeoRichData
- 5. Run the Magento update:
php bin/magento setup:upgrade
- 6. In a production environment, run DI compilation:
php bin/magento setup:di:compile
- 7. In a production environment, if the project requires it, generate static files:
php bin/magento setup:static-content:deploy
php bin/magento cache:flush
Manual installation
- Copy the module to the directory:
app/code/Kowal/SeoRichData
php bin/magento module:enable Kowal_SeoRichData
- 3. Run the Magento update:
php bin/magento setup:upgrade
php bin/magento cache:flush
Post-installation steps
After installation, the module adds a product attribute:
| Attribute | Meaning |
|---|
offer_item_condition | Product condition used to generate itemCondition in offers. |
The attribute supports the following values:
| Value in Magento | JSON-LD value |
|---|
DamagedCondition | https://schema.org/DamagedCondition |
NewCondition | https://schema.org/NewCondition |
RefurbishedCondition | https://schema.org/RefurbishedCondition |
UsedCondition | https://schema.org/UsedCondition |
If the product does not have an attribute value set, the module treats it as NewCondition.
Configuration scope
All configuration fields are available for the Default, Website, and Store View scopes, according to Magento settings.
Enabled, Show ..., and similar fields use standard Magento values:
| Value | Meaning |
|---|
Yes | The feature is enabled and can generate JSON-LD data. |
No | The feature is disabled. |
Breadcrumbs
This section is responsible for structured data for the navigation path.
| Field | Meaning | Values |
|---|
Enabled | Enables generation of BreadcrumbList data. | Yes, No |
Fixed Category Path | On the product page, uses the most specific category path when Magento does not provide full category context. | Yes, No |
Type | Defines the length of the breadcrumbs path generated for the search engine. | Default (Long), Short |
Values of the Type field:
| Value | Meaning |
|---|
Default (Long) | Full path, e.g. Store > Category > Subcategory > Product. |
Short | Shortened path, e.g. Store > Subcategory > Product. |
Include Your Site Name in Search Results
This section is responsible for WebSite data, which can help Google recognize the site name.
| Field | Meaning | Values |
|---|
Enabled | Enables generation of WebSite data. | Yes, No |
Website Name | The website/store name passed in structured data. | Text, e.g. the store name. |
Organization
This section is responsible for Organization data.
| Field | Meaning | Values |
|---|
Enabled | Enables generation of organization data. | Yes, No |
Organization Name | Company or store name. | Text; required field after enabling the section. |
Logo Url | Full URL of the organization logo. | URL to an image file. |
Description | Organization description. | Text. |
Description Length | Maximum number of description characters. | Number; empty means no truncation. |
Country | Organization country. | Country code from the Magento list. |
Region/State | Region or state. | Text. |
ZIP/Postal Code | ZIP/postal code. | Text. |
City | City. | Text. |
Street Address | Street and number. | Text. |
Sales | Sales department phone number. | Number in international format, e.g. +48.... |
Technical Support | Technical support phone number. | Number in international format. |
Customer Service | Customer service phone number. | Number in international format. |
The country from this section can be used as a fallback for the shipping country and return policy country if the relevant fields in the product section remain empty.
Social Profiles
This section adds the organization’s social profiles. For the data to make sense, the Organization section should be enabled.
| Field | Meaning | Values |
|---|
Enabled | Enables generation of social profile links. | Yes, No |
Facebook | Facebook profile URL. | Full URL. |
Twitter | Twitter / X profile URL. | Full URL. |
Google+ | Google+ profile URL. | Full URL; historical configuration field. |
Instagram | Instagram profile URL. | Full URL. |
YouTube | YouTube channel URL. | Full URL. |
LinkedIn | LinkedIn profile URL. | Full URL. |
Myspace | Myspace profile URL. | Full URL; historical configuration field. |
Pinterest | Pinterest profile URL. | Full URL. |
SoundCloud | SoundCloud profile URL. | Full URL. |
Tumblr | Tumblr profile URL. | Full URL. |
Empty fields are skipped.
Search Box
This section is responsible for SearchAction data, which can enable the store search box to be displayed in Google results.
| Field | Meaning | Values |
|---|
Enabled | Enables generation of site search data. | Yes, No |
Category Rich Data
This section is responsible for generating product data on category pages.
| Field | Meaning | Values |
|---|
Show Products Data | Adds structured data for products visible on the category page. | Yes, No |
Enabling this option can degrade category page performance because the module must collect data for many products.
Product Rich Data
This section is responsible for the main Product product data and offers data.
Basic product fields
| Field | Meaning | Values |
|---|
Enabled | Enables generation of product JSON-LD on the product page. | Yes, No |
Show Availability | Adds availability in offers. | Yes, No |
priceValidUntil Default Value | Default price validity date. | Date. |
Use “Special Price To” Value for priceValidUntil Snippet | If the product has an active special price and a Special Price To date, this date replaces the default value. | Yes, No |
Show Condition | Adds itemCondition in offers. | Yes, No |
Description | Defines the source of the product description in JSON-LD. | None, Product Short Description, Product Full Description, Page Meta Description |
Values of the Description field:
| Value | Meaning |
|---|
None | Does not retrieve the description from configuration; the code can use the product name as a fallback if the description is empty. |
Product Short Description | Uses the product short description. |
Product Full Description | Uses the product full description. |
Page Meta Description | Uses the page meta description. |
Configurable and grouped products
| Field | Meaning | Values |
|---|
Show Configurable Products as | Defines how offers are generated for configurable products. | Main Offer, List of Associated Products Offers, Aggregate Offer |
Show Grouped Products as | Defines how offers are generated for grouped products. | Main Offer, List of Associated Products Offers, Aggregate Offer |
Values:
| Value | Meaning |
|---|
Main Offer | Generates one offer for the main product. |
List of Associated Products Offers | Generates a separate offer for each simple or associated product. |
Aggregate Offer | Generates AggregateOffer with the lowest price, highest price, and number of offers. |
Ratings and reviews
| Field | Meaning | Values |
|---|
Show Rating | Adds aggregateRating and review to product data. | Yes, No |
Use Yotpo Reviews instead of Magento Reviews | Retrieves reviews from Yotpo instead of Magento Reviews. | Yes, No |
Rating Format | Defines the rating scale. | Percentage Scale, Numeric Scale |
Number of Reviews | Limit for the number of newest reviews added to JSON-LD. | Number; empty means all reviews. |
Values of the Rating Format field:
| Value | Meaning |
|---|
Percentage Scale | Ratings are interpreted on a percentage scale. |
Numeric Scale | Ratings are interpreted on a numeric scale. |
Integration with Yotpo requires the availability of a module that supports Yotpo. If the module is not installed, the Yotpo configuration should not be enabled.
Brand, manufacturer, and product identifiers
| Field | Meaning | Values |
|---|
Brand | Product attribute used to generate the brand property. | Any product attribute from the list. |
EAN / GTIN Attribute | Product attribute used as a global product identifier. | Any product attribute from the list. |
Manufacturer | Product attribute used to generate the manufacturer property. | Any product attribute from the list. |
The EAN / GTIN Attribute field generates the property depending on the number of digits:
| Number of digits | JSON-LD property |
|---|
| 8 | gtin8 |
| 12 | gtin12 |
| 13 | gtin13 |
| 14 | gtin14 |
| Other positive number of digits | gtin |
The module removes non-digit characters from the EAN / GTIN value before generating JSON-LD.
Shipping details
The shipping section is responsible for generating shippingDetails in offers. Data is added only when the section is enabled and has a complete set of required values.
| Field | Meaning | Values |
|---|
Show Shipping Details | Enables generation of shippingDetails. | Yes, No |
Shipping Country | Shipping country. | Country code from the Magento list; if empty, the country from the Organization section is used. |
Shipping Price | Shipping cost. | Number equal to or greater than 0; 0 means free shipping. |
Handling Time Min Days | Minimum order handling time. | Integer, days. |
Handling Time Max Days | Maximum order handling time. | Integer, days. |
Transit Time Min Days | Minimum transit time. | Integer, days. |
Transit Time Max Days | Maximum transit time. | Integer, days. |
The shipping cost currency is taken from the product offer currency.
Example meaning of values:
| Field | Example | Meaning |
|---|
Shipping Price | 0 | Free shipping. |
Handling Time Min Days | 0 | The order can be processed on the same day. |
Handling Time Max Days | 1 | Order processing takes a maximum of 1 day. |
Transit Time Min Days | 1 | Delivery takes at least 1 day. |
Transit Time Max Days | 5 | Delivery takes a maximum of 5 days. |
Merchant return policy
The return policy section is responsible for generating hasMerchantReturnPolicy in offers. Data is added only when the section is enabled and has the required values.
| Field | Meaning | Values |
|---|
Show Merchant Return Policy | Enables generation of hasMerchantReturnPolicy. | Yes, No |
Return Policy Country | Country where the return policy applies. | Country code from the Magento list; if empty, the country from the Organization section is used. |
Return Policy Category | Return policy type. | Finite Return Window, Returns Not Permitted, Unlimited Return Window |
Merchant Return Days | Number of days for returns. | Integer; required for Finite Return Window. |
Return Method | Supported return method. | -- Empty --, Return By Mail, Return In Store, Return At Kiosk |
Return Fees | Information about return fees. | -- Empty --, Free Return, Customer Responsibility, Return Shipping Fees |
Return Shipping Fee | Return shipping fee amount. | Number greater than 0; required only for Return Shipping Fees. |
Values of the Return Policy Category field:
| Value | JSON-LD value | Meaning |
|---|
Finite Return Window | https://schema.org/MerchantReturnFiniteReturnWindow | Return possible for a specified number of days. Requires Merchant Return Days. |
Returns Not Permitted | https://schema.org/MerchantReturnNotPermitted | Returns are not allowed. |
Unlimited Return Window | https://schema.org/MerchantReturnUnlimitedWindow | Return without a specified day limit. |
Values of the Return Method field:
| Value | JSON-LD value | Meaning |
|---|
-- Empty -- | no value | The return method is not added to JSON-LD. |
Return By Mail | https://schema.org/ReturnByMail | Return by mail. |
Return In Store | https://schema.org/ReturnInStore | Return in a physical store. |
Return At Kiosk | https://schema.org/ReturnAtKiosk | Return at a point/kiosk. |
Values of the Return Fees field:
| Value | JSON-LD value | Meaning |
|---|
-- Empty -- | no value | Fee information is not added to JSON-LD. |
Free Return | https://schema.org/FreeReturn | The return is free. |
Customer Responsibility | https://schema.org/ReturnFeesCustomerResponsibility | The customer bears the return cost. |
Return Shipping Fees | https://schema.org/ReturnShippingFees | The return has a specified return shipping fee. Requires Return Shipping Fee. |
The currency of the Return Shipping Fee field is taken from the product offer currency.
Custom Properties
The Custom Properties field allows you to add your own properties to product JSON-LD.
Format:
wlasciwosc_jsonld,kod_atrybutu
If only one element is provided, the module treats it both as the JSON-LD property name and the attribute code.
Default value:
skumpn,sku
Meaning of the default value:
| Line | Effect |
|---|
sku | Adds sku based on the sku attribute. |
mpn,sku | Adds mpn based on the sku attribute. |
Example of adding a custom attribute:
color,colormaterial,material
Recommended minimum configuration for products
To reduce Google Search Console warnings for product data, configure at least:
| Field | Recommendation |
|---|
Product Rich Data > Enabled | Yes |
Show Availability | Yes |
Brand | Select the attribute with the product brand. |
EAN / GTIN Attribute | Select the attribute with EAN / GTIN if products have a global identifier. |
Show Shipping Details | Yes, if the store has a uniform shipping policy that can be described in the configuration. |
Show Merchant Return Policy | Yes, if the store has a uniform return policy that can be described in the configuration. |
Custom Properties | Keep at least sku; optionally add mpn if the store has such an identifier. |
Clearing cache after configuration changes
After changing the configuration, run:
php bin/magento cache:flush
If the store uses additional HTTP cache, Varnish, or CDN, clear those cache layers as well.
Verifying operation
- Open the product page on the frontend.
- Check the page source and find:
<script type='application/ld+json'>
- 3. Verify that JSON-LD contains the expected fields, e.g.:
{ '@type': 'Product', 'brand': { '@type': 'Brand', 'name': 'Example Brand' }, 'gtin13': '5901234123457', 'offers': [ { '@type': 'Offer', 'shippingDetails': {}, 'hasMerchantReturnPolicy': {} } ]}
- 4. Test the product URL in the Google Rich Results Test tool or in Google Search Console.
Implementation notes
- Do not enable
shippingDetails or hasMerchantReturnPolicy if the values in the configuration do not match the store’s actual policy. - If shipping or return policies differ by product, region, shipping method, or cart, one global configuration may not be sufficient.
- After changing the
Brand, Manufacturer, or EAN / GTIN Attribute attributes, it is worth reindexing product data if the store uses cache or indexes that affect attribute reading. - In multilingual and multicurrency stores, check the configuration separately for each Store View.
