1 1. Principle
- 1.1 1.1 Straight fulfill order
- 1.2 1.2 Home delivery order
- 1.3 1.3 Tax states in Avalara
2 2. Configuration
3 3. Workflows
- 3.1 3.1 refresh_order_taxes
- 3.2 3.2 refund_order_taxes
- 3.3 3.3 void_order_taxes
4 4. Sending Avalara tax information with new orders
5 5. Limitations
- 5.1 5.1 Migration between environements

1. Principle

Calculation for e-commerce sales in the US depends on both the source of the stock (Sales Tax Nexus) and the destination of the order (Destination-Based sales Taxes).

A brand using an OMS can’t rely anymore on their e-commerce connector to a Tax provider to commit taxes as the source of the stock is known by the OMS.

Our tax provider connector and official connection to Avalara allows OneStock to address this issue by

Calculing taxes for our Order In Store module
Commiting taxes to Avalara when orders are dispatched (either for Order In Store or e-commerce orders)
Void or refund taxes to Avalara when items are canceled or returned

1.1 Straight fulfill order

The sequence explains how OneStock communicates with Avalara for the most basic use case: an order in store with the item taken from the store’s stock.

1.2 Home delivery order

The sequence shows how OneStock communicates with Avalara at different stages of the order lifecycle, explaining what is done in case the order is canceled or returned.

1.3 Tax states in Avalara

Taxes can have different states in Avalara:

Uncommitted : will match a status of a paid order but that is not in a final state in OneStock (processing, orchestrating), meaning that tax values can still change.
Committed : will match a fulfilled status in OneStock. At least an item is dispatched so taxes shouldn’t be modified.
Committed (refund) : A committed tax can have a negative value. It would mean that the tax was first committed before the order is returned and refunded.
Void : Happens when an order is cancelled entirely before any tax has been committed.

2. Configuration

2.1 Pre-requisites

Before you dig in your tax journey, be sure that you have the bellow ready with your OneStock Business Analyst.

An Order in Store saleschannel configured
Stores with US addresses
A payment provider configured and payment devices for the stores
Returns and refunds are configured for the Order in Store saleschannel

You will also need an access to an Avalara account. Our qualif environment is linked to Avalara in Sandbox so make sure to request this access to your Avalara contact.

2.2 Global tax configuration

Removed Line Item States : states of removed line items. When items are removed before the order is fulfiled, the tax provider needs to know that it has to commit a document without the items that have been cancelled by the client.
Commitable Parcel States : states of the parcels that needs to be commited

On you order, parcel and line item group workflows, you will have a new action : refresh_order_taxes.

This action will check that all your parcels are in the commitable parcel states that you’ve configured and that remaining items are in the removed line Item States to refresh the taxes in Avalara.

This is done to avoid unnecessary updates in Avalara.

Estimation Stock location : Stock location to be used for tax calculation as the source of stock. It can be overrided by sales channel.
Taxes Included In Price : Taxes are calculated and we display full prince including taxes. It can be overrided by sales channel.

2.3 Sales Channels tax configuration

Estimation Stock location : Stock location to be used for tax calculation as the source of stock
Taxes Included In Price : Taxes are calculated and we display full prince including taxes.

2.4 Configuring Avalara as the tax provider

Add Avalara as your tax provider in your sales channel configuration

You’ll have to do it for your Order In Store sales channel but also for the e-commerce sales channel if you are about to commit the taxes for all the client’s orders.

Our OneStock qualification environment is connected to Avalara sandbox.

Username : your Avalara identifier
Password : your Avalara password

After inputting your credentials, hit test connection

AvaTax Account Number
AvaTax Company Id

Find those two informations in your Avalara account

Disable tax recording at Avalara : if activated, OneStock will never commit the taxes
Avatax Company code : if your test connection has been done, a dropdown will display available value from your Avalara account

Location code : the location code (defined at Avalara) used by default if not defined at stock location level. To defined at stock location level you can go to the stock location detail page on the Taxes tab
Use endpoint identifier as location code : If activated, it will force the stock location id as the location code over the sales channel configuration and the stock location configuration.
Features language : The features language where we will search for the item data for HS Code, Item description, and Tax code
Default description : default description for items if not defined in the item feature
Description feature : name of the feature of the item which contains the description

Default HS Code : Default Harmonized System code for products if the item does not contain the HS Code feature configured bellow.
- Click here to lear more about HS codes
- Click here if you are searching the correct HS code for your product
HS Code feature : name of the product feature sent to OneStock that describe the HS code to use for this product
Default Tax Code : Default tax code for items if not defined in the item feature.
Tax code feature : Name of the feature of the item which contains the tax code.
- Click here to find valid tax codes

Shipping fees : configure which tax code and item code needs to be used for all your delivery options on the Order In Store

3. Workflows

To correctly update your taxes at the correct timing, you will have to add some action on your project workflows.

We’ve introduced 3 actions to be added in different parts of your workflows. Bellow we describe our recommendation for basic implementation of the taxes on where you should add those actions.

3.1 refresh_order_taxes

Workflows : order parcel line item groups

Allow to create or refresh a tax document for the order linked to the entity of your workflow.

Should be used to update taxes for direct capture payments. In case of deferred capture, the payment service will automatically request for the tax refresh.

The refresh will only be done for orders that are in final states, see 2.2 configuration above.

3.2 refund_order_taxes

Workflows : line item groups

Allow to refund taxes that have already been committed.

Use case to implement is for returns.

The action will not work on an order in store.

3.3 void_order_taxes

Workflows : order

Allows to delete a tax document for an uncommited tax.

Use case is for an order that is removed without being orchestrated.

4. Sending Avalara tax information with new orders

In order for OneStock to commit / void taxes that an ecommerce has declared but not committed to Avalara, the order data needs some additional informations.

Field	Description

Field	Description
order.taxes_information.provider_transaction_id string - mandatory	The transaction id in Avalara.
order.taxes_information.exemption_code string - optional	If there is a tax exemption for this order
order.shipping_fees[].taxes[].id Array object - optional	The id for the shipping fee line in Avalara In Avalara, the shipping fee is declared as an order line item. We use this to correctly commit and update the shipping fee taxes.
order.order_items[].pricing_details.taxes[].id string	The line id for each item in Avalara

{
    "order": {
        "id": "<order_id>",
        "types": [
            "ffs"
        ],
        "taxes_information": {
            "provider_transaction_id": "<avalara transactionid>",
            "exemption_code": "<exemption code>"
        },
        "sales_channel": "<onestock sales channel>",
        "customer": {
            "title": "<title>",
            "first_name": "<first name>",
            "last_name": "<last name>",
            "phone_number": "<phone number>",
            "email": "<email>"
        },
        "delivery": {
            "destination": {
                "address": {
                    "id": "",
                    "city": "<city>",
                    "contact": {
                        "title": "<title>",
                        "first_name": "<first name>",
                        "last_name": "<last name>",
                        "phone_number": "<phone number>",
                        "email": "<email>"
                    },
                    "lines": [
                        "<address line>"
                    ],
                    "regions": {
                        "country": {
                            "code": "<country code>"
                        }
                    },
                    "zip_code": "<zip code>"
                }
            },
            "type": "standard"
        },
        "pricing_details": {
            "currency": "<currency>",
            "address": {
                "id": "",
                "city": "<city>",
                "contact": {
                    "title": "<title>",
                    "first_name": "<first name>",
                    "last_name": "<last name>",
                    "phone_number": "<phone number>",
                    "email": "<email>"
                },
                "lines": [
                    "<address line>"
                ],
                "regions": {
                    "country": {
                        "code": "<country code>"
                    }
                },
                "zip_code": "<zip code>"
            },
            "price": 493
        },
        "shipping_fees": [
            {
                "currency": "<currency>",
                "price": 5,
                "original_price": 5,
                "taxes": [
                    {
                        "id": "<shipping fee line id>"
                    }
                ]
            }
        ],
        "order_items": [
            {
                "item_id": "15707351_BK_L",
                "quantity": 1,
                "pricing_details": {
                    "currency": "<currency>",
                    "original_price": <price>,
                    "price": <price>,
                    "original_unit_price": <price>,
                    "unit_price": <price>,
                    "taxes": [
                        {
                            "id": "<item line id in avalara>"
                        }
                    ]
                }
            },
            {
                "item_id": "15707351_BK_L",
                "quantity": 1,
                "pricing_details": {
                    "currency": "<currency>",
                    "original_price": <price>,
                    "price": <price>,
                    "original_unit_price": <price>,
                    "unit_price": <price>,
                    "taxes": [
                        {
                            "id": "<item line id in avalara>"
                        }
                    ]
                }
            }
        ]
    }
}

5. Limitations

5.1 Migration between environements

12.6 At the moment, global configurations can be migrated between environments but Sales Channel configurations and providers configured for them are not migrated

Documentation

Tax Connector - Avalara