Displays the ‘Related Products’ smart category which displays products related to the current product being viewed, or a specified product.

shopp('storefront', 'related-products', 'options')

@param string $object the object or object.tag combination, if object.tag is used, the tag parameter can be omitted
@param string $tag the tag, can be hyphenated or not. Prefix with 'get' as shorthand for the return=true option
@param mixed $options associative array, or url-style name=value pairs separated by ampersands (&). Each pair is passed to the theme api tag as an option.
@returns string Markup for the Related Products smart collection

Displays the Related Products smart collection.

The Related Products smart collection will show products related to the current product (the product loaded into the current product context) or a specified product using the product option. The relationships are not automatic, but instead managed by product tagging. To create a relationship between products simply add the same tag name to each product that should be related. This allows catalog managers to control the products that appear in the Related Products smart collection for any given product.

This collection differs from the shopp(‘storefront’,’tag-products’) smart collection because it factors in all of the product tags, not just one. The more tags that products share in common, the stronger their relationship. Products are then sorted according to the strength of their relationship (the number of tags that are shared) from strongest relationships to the weakest.

As an example, an imaginary product like Bicycle KX-222 might have complementary products that fit that unique product’s design (such as water bottles, cushioned seats, etc). You might tag all of those products (and the Bicycle KX-222 product) with a tag to indicate the relationship such as: bicycle-kx-222-upsells

Simply add the Theme API tag to the product.php template file (see the examples below) and the related products will be displayed like a category of products on the product page. By default, it will automatically use the product being displayed on the product page (because the product will be the “current product context”).

If you would like to use the Related Products collection in other template files where no implicit product context exists (such as a sidebar widget, or the WordPress theme’s footer.php), you can use the product option to specify a product to target for the relationship.


  • product: The ID of a product to load related products from. By default, uses the currently loaded/requested product.
  • title: Specifies the title to be shown for the category layout overriding the default category title.
  • controls: Default is off. Overrides the display of “control” elements in the category.php template that would otherwise be shown. Used to highlight a selection of products in a category without all of the extra category controls.
  • show: No default value. Limits the number of products to show in the category display. Without a limit, this category will show all the products in your catalog (no matter what category they are in). Without a specified limit, a built-in hard limit of 1000 products is used to prevent the server’s resources from being totally consumed.
  • load: Default is false. Loads the category into memory, making it available for using shopp(‘storefront’,’tag-products’) rather than displaying the category using the shopp(‘storefront’,’tag-products’).
  • pagination: Default is numeric. Set to alpha this option will use alphabetic pagination, otherwise it will default to numeric.
  • order: Default is bestselling. Possible settings include: bestselling, highprice, lowprice, newest, oldest, random, and title

Universal Options

All Theme API calls have these options.

  • return: when set to true, 1, or on, this option forces the tag to return the value instead of displaying/echoing the value to the page. Alternatively, prefix the tag parameter with get to get the same effect. All theme api tags that return a boolean value will return by default.
  • echo: when set to false, 0, or off, this option forces the tag to display the value to the page. This is the default for all non-boolean tags.
  • is: when set to true, 1, or on, this option will evaluate the return of the theme api call as a boolean true or false value. See how values are converted to boolean.


Show Related Products of Current

<?php shopp('storefront','related-products','show=5'); ?>

Shows 5 products related to the current product being viewed (the currently requested or loaded product).

Show Related Products of a Specific Product

<?php shopp('storefront','related-products','product=125&show=10'); ?>

Shows 10 products related to the product tags of a product with a system ID of 125.

See Also

  1. It should be mentioned that related products are based on products with the same tag. If you have a bunch of widgets, tag each product with “widget” and the Related Products smart collection will include all of those products tagged as a widget.

    January 31st   #

  2. Looks like the “show” option is broken. In the plugin folder the file shopp/core/model/Collection.php needs the following line added to line 2022:

    if ( isset($options[‘show’]) ) $this->loading[‘limit’] = $options[‘show’];

    June 8th   #

  3. It was fixed in the 1.3.4 release.

    June 17th   #

You must be logged in to post a comment.

© Ingenesis Limited. Shopp™ is a registered trademark of Ingenesis Limited.