Feature Alert 32 -
This month’s feature alert is dedicated to our US customers whose projects went live over the last weeks. Our platform entered the US market with the launch of U.S. Elite, Blue Star Nutraceuticals and Loomstate.
To make this happen our platform had to be extended in order to handle the tax requirements that are specific to the United States. Not only the taxes on purchased goods can differ from state to state in the US, moreover their taxes are calculated based on different tax portions, like for the state, the county and the city.
In the following we’ll explain how these requirements have been addressed by our cloud-based commerce platform.
Different Tax Modes
A requirement we got form our US customers was the integration with external services that are specialized in calculating the very fragmented taxes compliant to US laws.
To support that we introduced different tax modes in our platform with which the built-in tax calculation can be disabled and left to external 3rd party services. For that case the client application sets the TaxMode for a Cart to
External what prevents the platform from calculating any taxed price for the content of the cart. The platform-internal tax calculation based on the cart’s shipping address is applied if the tax mode is set to
Platform. In this mode the cart contains the TaxedPrice once the shipping address is set. The third tax mode
Disabled has been introduced for testing purposes. This mode allows ordering carts with no taxes added without fulfilling the conditions the other two tax modes require for placing an order.
External Tax Mode
External tax mode is meant to be used for scenarios in which the tax rates are retrieved from external services instead of the platform’s built-in tax calculation.
When this mode is applied to the cart the client application will need to set the tax rates for
customLineItems as well as
shippingInfo either during
- creation of the cart (with LineItemDraft, CustomLineItemDraft), and
- adding the items to the cart (with update actions add LineItem, add CustomLineItem, set ShippingMethod, or set Custom ShippingMethod)
- setting the tax rate explicitly via update actions Set LineItem TaxRate, Set CustomLineItem TaxRate, and Set ShippingMethod TaxRate before the cart can be ordered.
For all those methods the tax rates are provided as ExternalTaxRateDraft objects allowing to specify tax rates for each US state individually as it is possible for the TaxRates in the tax categories. Additionally, it can be determined how the tax rate is composed of certain sub rates, e.g. for state, county, and city. Each SubRate is defined by its name and the percentage of its fraction on the total tax rate.
Platform Tax Mode
In case the
Platform TaxMode has been chosen when creating a cart the
taxedPrice field in the Cart is calculated by the platform according to the TaxRate of each line item, custom line item and the
shippingRate defined for the ShippingInfo in the cart once the shipping address is set.
Taxed Item Price
Another feature we recently introduced is the addition of the TaxedItemPrice that has been added to the LineItem, CustomLineItem, and ShippingInfo.
This new object contains the
totalNet and the
totalGross price for the respective (custom) line item or shipping info. Before we introduced that object the clients had to calculate the gross and net price with product price and tax rate themselves.