How to Handle Taxes with Store Builder Library
Overview
This article provides a strategy for handling the various VAT, GST, and tax scenarios in your SBL shopping cart.
When designing your web pages to use Store Builder Library (SBL), you may want to create a full shopping cart experience. In that case, you should 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 handling the various tax scenarios in your SBL shopping cart.
- The Order Object Response
- Supplying Required Details to the Session
- Displaying Tax Information to the Customer In Your Cart
- Displaying Pre-Tax Price Information to the Customer In Your Cart (for Stores Using Net Pricing)
The Order Object Response
Each time the order details are updated (e.g., by adding an item to the cart), the library immediately returns a response containing all details of the current order session. This is called the order object response. You can find an example of the order object response 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 may be helpful for you in handling and displaying taxes:
| Field | Data Type | Description |
|---|---|---|
| taxExemptionAllowed | Boolean | based 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 |
| taxExempt | Boolean | indicates whether or not the current order is exempt from tax |
| total | String | the order total; may or may not include tax (see taxPriceType) |
| totalValue* | Number | the order total, without the currency symbol |
| tax | String | the amount of tax currently applied to the order |
| taxValue* | Number | the amount of tax currently applied to the order, without the currency symbol |
| totalWithTax | String | the order total, including tax |
| totalWithTaxValue* | Number | the order total, including tax, without the currency symbol |
| taxPriceType | String | "included" or "added"; indicates whether tax is included in the subtotal or added to the subtotal |
| taxType | String | "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) |
| taxRate | String | the 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) |
| priceWithoutTax | String | the total price of the current item before any applicable taxes; only included in the order object response for Stores using net pricing mode |
| priceValueWithoutTax | Number | the total price of the current item before any applicable taxes, without the currency symbol; only included for Stores using net pricing mode |
| priceWithoutTaxAndDiscount | String | unit price of the current item, before tax and any coupon discounts; only included for Stores using net pricing mode |
| priceValueWithoutTaxAndDiscount | Number | unit price of the current item, before tax and any coupon discounts, without the currency symbol; only included for Stores using net pricing mode |
Note
Supplying Required Details to the Session
To retrieve accurate tax details from the library, you must first collect the following transaction details and update the session with them. Since non-U.S. taxes are assessed nationally, and U.S. sales taxes depend on the customer's postal code, the requirements can differ depending on the customer's country.
Demonstration Video
| Data | Purpose | Method(s) |
|---|---|---|
| when country != "US" | ||
| country | used to determine whether or not VAT, GST, or Japanese consumption tax apply, and at what rate |
|
| taxID | for 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" | ||
| postalCode | determines 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 taxType, tax, 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 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 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. Also, you could use totalWithTax or totalWithTaxValue to show the grand total with sales tax.