Catalog Price Object Examples

As a theme developer, you can use the Catalog Price Object to highlight the savings that a merchant is offering over the MSRP (Retail Price) directly on the storefront by simply referencing the product’s Catalog Price Object and the correct property for the product.

Merchants can use Control Panel options to set the following prices for a catalog product:

Control Panel Field Description
Default Price This 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).
Cost Price The product's Cost Price 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 price field is meant for reports and third-party accounting integrations.
MSRP (Retail Price) This field contains the Manufacturer's Standard Retail Price, also known as the list price. MSRP is the manufacturer's suggested retail price, a price recommended for the sale of an item in all retail outlets.
Sale Price This field is the product's reduced store price.

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 Price
  • Retail Price (MSRP)

No Sale Price is defined for the product.

Product in Control Panel (no Sale Price defined)

#### Product in Control Panel (no Sale Price defined)

A corresponding Catalog Price Object for the product will be structured as follows:

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
        }
      }
    }
  }

Items to note about the Catalog Price Object above:

  • without_tax – this property maps to the control panel’s Default Price field.
  • rrp_without_taxrrp is an abbreviation for “regular retail price.” This property maps to the control panel’s MSRP (Retail Price) field.
  • saved – this property 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 Price
  • Retail Price (MSRP)
  • Sale Price

Product in Control Panel (Sale Price defined)

#### Product in Control Panel (Sale Price defined)

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
        }
      }
    }
  }

Items to note about the Catalog Price Object above:

  • The sale_price_without_tax property maps to the product’s effective price is 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.
  • The regular store price is now displayed in an added property called non_sale_price_without_tax.

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 the standard store price with a strikeout across it, placed next to the Sale Price, 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 an on sale product]  ...
  {{/or}}

Catalog Price Object Examples Including and Excluding Tax

Depending on how the store has been set up in the Control Panel’s Store Setup > Tax > Configure Tax Display Settings, the Catalog Price Object properties may represent prices in 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

#### Configure Tax Display Settings

No Sale Price Defined in Control Panel

Assume that a merchant has defined the following for a tax configurations for a product in the Control Panel:

  • Show prices on Product Pages Including and excluding tax
  • Flat 10% tax rate configured

There is no defined a Sale Price for the product.

A corresponding Catalog Price Object for the product 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"
  }
}

Items to note about the Catalog Price Object example above:

  • with_tax: This property represents the without_tax value plus a 10% tax markup.
  • rrp_with_tax: This property represents the rrp_without_tax value plus a 10% tax markup.

Tax Display Configurations

You would see these same properties and values if the Control Panel setting had been Including tax (as opposed to Including and excluding tax). These properties and values would not be available for a Control Panel setting of Excluding tax.

Sale Price Defined in Control Panel

Assume that a merchant has defined the following for a tax configurations for a product in the Control Panel, alongside a defined Sale Price:

  • Show prices on Product Pages Including and excluding tax
  • Flat 10% tax rate configured
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"
  }
}

Items to note about the Catalog Price Object above:

  • The non_sale_price_without_tax and non_sale_price_with_tax properties represent the standard store price with and without tax.
  • The sale_price_without_tax and sale_price_without_tax represent the product’s defined Sale Price.
  • The saved 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.

Control-Panel Field Catalog Price Object Property Description
Default Price (excluding tax)
  • if Sale Price defined:
  • {{ product.price.non_sale_price_without_tax }}
  • if no Sale Price defined
  • {{ product.price.without_tax }}
The standard store price for the product.
Default Price (including tax)
  • if Sale Price defined:
  • {{ product.price.non_sale_price_with_tax }}
  • if no Sale Price defined
  • {{ product.price.with_tax }}
    The standard store price for the product, with tax.
    Cost Price Cost Price 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 (Retail Price) (excluding tax) {{ product.price.rrp_without_tax }} Represents the product’s list price, or Manufacturer's Standard Retail Price (Retail Price).
    MSRP (Retail Price) (including tax) {{ product.price.rrp_with_tax }} Used to represent the product’s list price or Manufacturer's Standard Retail Price (MSRP), 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 (Retail Price) (Default Price - MSRP (Retail Price)) {{ product.price.saved }} The customer’s savings on the effective price versus list price.

    Resources

    Related Articles