Perch Shop


The following namespaced tags are used by Perch Shop.

Namespace Used for
perch:shop All shop tag types except those detailed below
perch:cartitems Tag pair around items in the cart
perch:cartitem Used for template tags for individual cart items
perch:productopts Product options (size, colour)
perch:productopt Single product option
perch:productvalues Product option values (M, L, red, blue)
perch:productvalue Single product option value
perch:variants Product variants
perch:variant Single product variant

Master Templates

The master templates for Shop are as follows. All templates are within perch_shop/templates/shop and an individual template should be copied to the corresponding location within your local perch/templates/shop folder before editing.

Entity Template
Customer address addresses/address.html
Brand brands/brand.html
Cart cart/cart.html
Currency currencies/currency.html
Customer customers/customer.html
Email emails/email.html
Order orders/order.html
Order status orders/status.html
Product products/product.html
Product file products/file.html
Product options product/option.html
Product variants product/variant.html
Promotions promotions/promotion.html
Shipping methods shippings/shipping.html
Shipping zones shipping/zone.html
Tax groups tax/group.html
Tax locations tax/location.html

Template IDs

Perch Shop exposes the following variables as values for the id attribute in template tags.

Cart tags

Tag Description
product_count Number of unique products in the cart
item_count Number of individual items in the cart
shipping_id Shipping ID for the shipping method in use for the cart
shipping_method The name of the shipping method being used
shipping_weight The combined weight of items being shipped
shipping_tax Tax paid on selected shipping method, defaults to 0
shipping_tax_formatted Formatted value for shipping tax
shipping_tax_rate Rate used for shipping tax
shipping_with_tax Shipping charge with tax added
shipping_with_tax_formatted Shipping charge with tax added, formatted
shipping_without_tax Cost of shipping without tax
shipping_without_tax_formatted Cost of shipping without tax, formatted
total_items Total value of the items in the cart
total_items_formatted Total value of the items in the cart, formatted
total_items_tax The total tax amount on items in the cart
total_items_tax_formatted The total tax amount on items in the cart, formatted
total_shipping The total shipping amount
total_shipping_formatted The total shipping amount, formatted
total_shipping_tax The total tax amount on shipping
total_shipping_tax_formatted The total tax amount on shipping, formatted
total_items_with_shipping The total value of items and shipping combined
total_items_with_shipping_formatted The total value of items and shipping combined, formatted
total_tax The total amount of item and shipping tax combined
total_tax_formatted The total amount of item and shipping tax combined, formatted
total_discounts Total of discounts applied
total_discounts_formatted Total of discounts applied, formatted
total_items_discount The total value of discounts applied to items in the cart
total_items_discount_formatted The total value of discounts applied to items in the cart, formatted
total_items_tax_discount The total value of discounts applied to tax
total_items_tax_discount_formatted The total value of discounts applied to tax, formatted
total_items_discounted Total value of the items in the cart with discounts applied
total_items_discounted_formatted Total value of the items in the cart with discounts applied, formatted
total_items_discounted_with_tax Total value of the items in the cart with discounts and tax applied
total_items_discounted_with_tax_formatted Total value of the items in the cart with discounts and tax applied, formatted
total_shipping_discount Total value of discounts applied to shipping
total_shipping_discount_formatted Total value of discounts applied to shipping, formatted
total_shipping_tax_discount Total value of shipping with discounts applied
total_shipping_tax_discount_formatted Total value of shipping with discounts applied, formatted
total_tax_discount Total amount of discount applied to tax
total_tax_discount_formatted Total amount of discount applied to tax, formatted
total_discounts_with_tax Combined total of item, shipping and tax discounts
total_discounts_with_tax_formatted Combined total of item, shipping and tax discounts, formatted
grand_total Grand total - what your customer will pay
grand_total_formatted Grand total, formatted
shipping_weight Shipping weight
currency_id Currency ID for the currency used for this cart
currency_code Currency code
currency_name Currency name
currency_symbol Currency symbol

Cart Item tags

Tag Description
identifier The unique ID of this entry in the cart
id Alias for identifier
qty The quantity of this item in the cart
productID The unique ID of the product
is_variant True or false, if the item is a variant
variant_desc The variant description of the item, if it is a variant
sku The product SKU
title Title of the product
slug Product slug based on the title
brand The product brand (use with type="shop_brand"
category The product categories (use with perch:categories tags)
catalog_only True or false, if the product is available for online sale
requires_shipping True or false, requires physical shipping
weight The weight of the item
width The width of the item
height The height of the item
depth The depth of the item
price Item price (use with type="shop_currency_value")
sale_price Sale price (use with type="shop_currency_value")
trade_price Trade price (use with type="shop_currency_value")
on_sale True or false, if the item is currently discounted
tax_group The product’s tax group (use with type="shop_tax_group")
stock_level The number of items in stock
stock_status The current stock status (use with type="shop_stock_status")
max_in_cart The maximum allowable quantity of this item per cart
discount The amount of discount applied to the item
price_with_tax The price with tax included
price_with_tax_formatted The price with tax included, formatted
price_without_tax The price without tax
price_without_tax_formatted The price without tax, formatted
tax_discount The about of discount applied to the tax
tax_rate The rate at which tax has been calculated
total_tax The amount of tax
total_tax_formatted The amount of tax, formatted
total_with_tax The line total including tax
total_with_tax_formatted The line total including tax, formatted
total_without_tax The line total excluding tax
total_without_tax_formatted The line total excluding tax, formatted

Brand tags

Tag Description
title The name of the brand
slug The URL-safe slug version of title
description A description of the brand
image An image representing the brand

Editing templates

As with all Perch Add-ons, Shop comes with some default templates. These are stored in perch/addons/apps/perch_shop/templates/shop. Inside that folder are subfolders for the different parts of Shop, for example for the Cart that is the folder cart which includes a simple cart.html template. This will be used if you do not specify your own template name when displaying the cart, and if there is no template with the same name in your custom templates folder at perch/templates/shop.

You should not edit the templates that are inside the app folder. Before making any changes copy the template you wish to change into its subfolder inside perch/templates/shop/ You can then make any changes you want and the changes will not be overwritten when you update the add-on.

For example, to edit the default product template, you would copy:


to your local templates folder as:


Your edited template will then be used in preference, and it won’t be overwritten when you apply updates to the Shop app.