How to Handle Taxes with Store Builder Library

Last modified February 22, 2019

This article applies to Contextual Commerce. (Looking for Classic Commerce documentation?)

When designing your web pages to use Store Builder Library (SBL), you may want to create a full shopping cart experience. In that case, we recommend that you take into account the possible taxes, such as VAT, GST, and sales tax, that may apply to each order. This article provides a strategy for handing the various tax scenarios in your SBL shopping cart.

The Order Object Response

Each time the order details are updated (e.g. by invoking any SBL function), the library will immediately return a response containing all details of the current order session; that is, the order object response. An example of the order object response can be found here. You should design your page to parse the order object response each time the order details are updated.

The order object response contains several fields that will be helpful for you in handling and displaying taxes:

Field

Data Type

Description

taxExemptionAllowedBooleanbased on order country, indicates whether or not it is possible to supply an ID (e.g. VAT ID, GST ID) and remove tax from the order
taxExemptBooleanindicates whether or not the current order is exempt from tax
totalStringthe order total; may or may not include tax (see taxPriceType)
totalValue*Numberthe order total, without the currency symbol
taxStringthe amount of tax currently applied to the order
taxValue*Numberthe amount of tax currently applied to the order, without the currency symbol
totalWithTaxStringthe order total, including tax
totalWithTaxValue*Numberthe order total, including tax, without the currency symbol
taxPriceTypeString"included" or "added"; indicates whether tax is included in the subtotal or added to the subtotal
taxTypeString"US" (US state/local sales tax) | "VAT" (Value Added Tax, e.g. in the EU) | "GST" (Goods and Services Tax, e.g. in Australia) | "JP" (Japan's Consumption Tax)
taxRateStringthe tax rate applied to the current order if taxExempt is false, expressed as a percentage; "0%" if unknown (e.g. country / postal code have not been supplied)
priceWithoutTaxStringthe total price of the current item before any applicable taxes; only included in the order object response for Stores using net pricing mode.
priceValueWithoutTaxNumberthe total price of the current item before any applicable taxes, without the currency symbol; only included for Stores using net pricing mode.
priceWithoutTaxAndDiscountStringunit price of the current item, before tax and any coupon discounts; only included for Stores using net pricing mode.
priceValueWithoutTaxAndDiscountNumberunit price of the current item, before tax and any coupon discounts, without the currency symbol; only included for Stores using net pricing mode.

Note

*Fields with "Value" in the name are alternative versions of the corresponding fields, provided in case you want to render only the numeric values or format the data differently (e.g. with no currency symbol).

Supplying Required Details to the Session

In order to retrieve accurate tax details from the library, you must first collect the following details and update the session with them. Since non-U.S. taxes are assessed nationally and U.S. sales taxes depend on customer's postal code, the requirements can differ depending on the customer's country.

Demonstration Video

Check out this quick demonstration video showing one method of applying the customer's tax ID to the SBL session.
DataPurposeMethod(s)

when country != "US"

countryused to determine whether or not VAT, GST, or Japanese consumption tax apply, and at what rate
taxIDfor customers who have exempt or deferred status (usually organizations), in countries where taxExemptionAllowed is true,
taxID is used to validate the string supplied by the customer and set taxExempt to true when applicable, removing tax from the order
when country == "US"
postalCodedetermines whether or not sales tax applies, and at what rate


Displaying Tax Information to the Customer In Your Cart


If taxExempt = true:

  • Display the order total to the customer using either total or totalWithTax, which will be equal.
  • Communicate that the order is "exempt from tax".
  • Communicate the amount to be charged (something like "Pay XXX" or "XXX will be charged to the selected payment method"), using the field totalWithTax.

If taxExempt = false and taxPriceType == "added":

  • Display the pre-tax total to the customer using the total field. You might want to provide a descriptive label such as "Subtotal" for this field.
  • On a separate line or in a separate section, display the amount of tax applied to the order using the tax field. You might want to provide a descriptive label in addition to the variable here, as well.
  • Communicate the amount to be charged (something like "Pay XXX" or "XXX will be charged to the selected payment method"), using the field totalWithTax.

If taxExempt = false and taxPriceType == "included":

  • Display the total amount to the customer using either total or totalWithTax, which will be equal.
  • Near the total (e.g. directly below), use the taxTypetax, and taxRate fields to communicate that the total includes applicable tax. For example, "Includes tax of taxType at taxRate" might be rendered as "Includes €5.69 of VAT at 19%".
  • Communicate the amount to be charged (something like "Pay XXX" or "XXX will be charged to the selected payment method"), using the field totalWithTax.


Displaying Tax Information In Your Cart Copy


Displaying Pre-Tax Price Information to the Customer In Your Cart (for Stores Using Net Pricing)

For Stores using net pricing mode, Store Builder Library's order object response includes two fields you can use to directly display item-level pre-tax prices to your customers:

  • priceWithoutTax is a string that indicates the price of the current item without applicable tax
  • priceValueWithoutTax is a numeric value representing the current item's price before tax (with no currency symbol)

In the context of an itemized shopping cart, you could then use either tax or taxValue from the order object response to render the total tax amount, and use totalWithTax or totalWithTaxValue to show the grand total with sales tax.