StorefrontStencilThemesPage Context

Using Catalog Price Objects

As a theme developer, you can use the catalog price object to highlight the savings that a merchant is offering over the MSRP directly on the storefront by referencing the product’s price object and the correct property for the product.

Merchants can use control panel options to set the following prices for a catalog product:

FieldDescription
Default PriceThis is the product’s standard store price. The Excluding/Including Tax indicator to the right of the Default Price field is applicable to all price fields (Cost, MSRP, Sale Price).
CostThe product’s cost property is never returned to the storefront by design. Generally, merchants would not want to reveal the true cost of goods to shoppers. The Cost field is meant for reports and third-party accounting integrations.
MSRPThis field contains the manufacturer’s suggested retail price, a price recommended for the sale of an item in all retail outlets.
Sale PriceThis field is the product’s reduced store price. A sale price set to zero will result in no charge to the shopper.

These options and assigned values are each represented in the catalog price object, allowing theme developers to pull the information and render it onto the storefront to highlight the savings offered by a merchant.

Catalog price object examples excluding tax

No sale price defined in control panel

Assume that a merchant has defined the following for a product in the control panel:

  • Default Price
  • Cost
  • MSRP

A corresponding catalog price object for the product will be structured as shown below:

Catalog price object, no sale price defined
{
  "product": {
    // ...
  },
  "price": {
    "without_tax": {
      "formatted": "$20.00",
      "value": 20
    },
    "tax_label": "Sales Tax",
    "rrp_without_tax": {
      "formatted": "$25.00",
      "value": 25
    },
    "saved": {
      "formatted": "$5.00",
      "value": 5
    },
    "retail_price_range": {
      "min": {
        "without_tax": {
          "formatted": "$25.00",
          "value": 25
        }
      },
      "max": {
        "without_tax": {
          "formatted": "$25.00",
          "value": 25
        }
      }
    }
  }
}

In this example:

PropertyDescription
without_taxThis property maps to the control panel’s Default Price field.
rrp_without_taxrrp stands for “regular retail price.” This property maps to the control panel’s MSRP field.
savedThis value is the difference between the existing values for without_tax (Default Price) and rrp_without_tax (MSRP).

Sale price defined in control panel

Assume that a merchant has defined the following for a product in the control panel:

  • Default Price
  • Cost
  • MSRP
  • Sale Price

A corresponding catalog price object for the product will be structured as shown below:

Catalog price object, sale price defined
{
  "product": {
    // ...
    "price": {
      "without_tax": {
        "formatted": "$15.00",
        "value": 15
      },
      "tax_label": "Sales Tax",
      "sale_price_without_tax": {
        "formatted": "$15.00",
        "value": 15
      },
      "non_sale_price_without_tax": {
        "formatted": "$20.00",
        "value": 20
      },
      "rrp_without_tax": {
        "formatted": "$25.00",
        "value": 25
      },
      "saved": {
        "formatted": "$10.00",
        "value": 10
      },
      "retail_price_range": {
        "min": {
          "without_tax": {
            "formatted": "$25.00",
            "value": 25
          }
        },
        "max": {
          "without_tax": {
            "formatted": "$25.00",
            "value": 25
          }
        }
      }
    }
  }
}

In this example:

PropertyDescription
sale_price_without_taxThis property maps to the product’s effective price in the control panel’s Sale Price field. The sale_price_without_tax property will directly expose the sale price set on a base product, variant, or price record.
non_sale_price_without_taxThis property displays the regular store price.

Properties noted will only be displayed if a sale price is set on the product.

Prices and conditional logic example

Stencil structures product prices for backward compatibility with the BigCommerce platform’s traditional treatment of prices. This behavior enables you to add logic that determines whether to display a strikeout price on the storefront.

The example below tests for the presence of the sale_price_without_tax property. (You could also look for the sale_price_with_tax property.) The presence of the sale_price_without_tax property means that the product has been given a sale price.

With the logic below, the page will display a strikeout standard price next to the Sale Price field, indicating the current selling price of the product.

Conditional logic
  {{#or price.sale_price_without_tax price.sale_price_with_tax}}
     ... [code to display on-sale strikeout pricing or content for a discounted product]  ...
  {{/or}}

Catalog price object examples including and excluding tax

Depending on the store’s Tax Display Settings, the price object will display prices in one of the following ways:

  • Including tax
  • Excluding tax
  • Including and excluding tax

This display setting affects how values are returned in the catalog price object and how the values appear on storefront pages.

Configure tax display settings

No sale price defined in control panel

Assume that a merchant has defined the following tax configurations for a product in the control panel:

  • Show prices on product pages including and excluding tax
  • Use a flat rate of 10% tax

There is no defined sale price for the product.

A corresponding catalog price object will be structured as shown below:

Product including and excluding tax, no sale price defined
{
  "product": {
    "price": {
      "with_tax": {
        "formatted": "$165.00",
        "value": 165
      },
      "without_tax": {
        "formatted": "$150.00",
        "value": 150
      },
      "rrp_with_tax": {
        "formatted": "$275.00",
        "value": 275
      },
      "rrp_without_tax": {
        "formatted": "$250.00",
        "value": 250
      },
      "saved": {
        "formatted": "$110.00",
        "value": 110
        },
      "tax_label": "Tax"
    }
  }
}

In this example:

PropertyDescription
with_taxThis property represents the without_tax value plus a 10% tax markup.
rrp_with_taxThis property represents the rrp_without_tax value plus a 10% tax markup.

Tax display configurations

The same properties and values are returned for Including tax and Including and excluding tax display settings. These properties and values are not available for a control panel setting of Excluding tax.

Sale price defined in control panel

Assume that a merchant has defined the following tax configurations for a product in the control panel, alongside a defined sale price:

  • Show prices on product pages including and excluding tax
  • Use a flat rate of 10% tax
Product including and excluding tax, sale price defined
{
  "product": {
    "price": {
      "with_tax": {
        "formatted": "$135.30",
        "value": 135.3
      },
      "without_tax": {
        "formatted": "$123.00",
        "value": 123
      },
      "sale_price_without_tax": {
        "formatted": "123.00",
        "value": 123
      },
      "sale_price_with_tax": {
        "formatted": "135.30",
        "value": 135.3
      },
      "rrp_with_tax": {
        "formatted": "$275.00",
        "value": 275
      },
      "rrp_without_tax": {
        "formatted": "$250.00",
        "value": 250
      },
      "saved": {
        "formatted": "$139.70",
        "value": 139.7
      },
      "non_sale_price_without_tax": {
        "formatted": "$150.00",
        "value": 150
      },
      "non_sale_price_with_tax": {
        "formatted": "$165.00",
        "value": 165
      },
      "tax_label": "Tax"
    }
  }
}

In this example:

PropertyDescription
non_sale_price_with_taxThis property represents the standard store price with tax.
non_sale_price_without_taxThis property represents the standard store price without tax.
sale_price_with_tax and sale_price_without_taxThese properties represent the product’s defined sale price.
savedThis value is based on the difference between the with_tax and non_sale_price_with_tax values.

Control panel quick reference

The table below explains the mapping between the control panel fields and the catalog price object properties and values.

FieldCatalog Price Object PropertyDescription
Default Price (excluding tax)
  • Sale Price is defined:
    • {{ product.price.non_sale_price_without_tax }}
  • Sale Price is not defined:
    • {{ product.price.without_tax }}
The standard store price for the product.
Default Price (including tax)
  • Sale Price is defined:
    • {{ product.price.non_sale_price_with_tax }}
  • Sale Price is not defined:
    • {{ product.price.with_tax }}
The standard store price for the product, with tax.
CostCost is not returned in the catalog price object.This field represents true cost of goods, and is typically meant for reports and third-party accounting integrations.
MSRP (excluding tax){{ product.price.rrp_without_tax }}This field represents the product’s list price, or the manufacturer’s suggested retail price.
MSRP (including tax){{ product.price.rrp_with_tax }}This field represents the product’s list price, or the manufacturer’s suggested retail price, including tax.
Sale Price (excluding tax){{product.price.sale_price_without_tax}}This product’s discounted/sale price.
Sale Price (including tax){{ product.sale_price_with_tax }}This product’s discounted/sale price, with tax.
Difference between Default Price and MSRP (Default Price - MSRP){{ product.price.saved }}The customer’s savings on the effective price versus list price.

Resources