Collapse Menu
Docs Home
Extensibility Options
Contact Support

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

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:

FieldData TypeDescription
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. They are 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

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

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

Try FastSpring

Get a free account and see why FastSpring is the ecommerce partner of choice for software providers around the world. Try our full-service ecommerce solution today to unlock revenue growth for your online company.