This documentation page explains at a C4 level how the Avalara connector works.

Use this documentation if you need to review / assess at a very low level if the data that are transmitted to Avalara and what APIs calls are used.

C4 diagrams

Context

OIS

Web

Authentication

All requests to the Avalara APIs are inputted with the following header.

Authorization: Basic base64('<API login>:<API password>')

The credentials used are configured in your sales channel configuration where "<API login>" is from avalara.credentials.username and "<API password>" fromavalara.credentials.password.

Specific header

There is a X-Avalara-Client header sent with every request to Avalara to identifiy that the request comes from OneStock

X-Avalara-Client: xxxxx

Configuration

The configuration can be done in your Sales Channel.

0. Before starting

For the majority of calls we use the same endpoint CreateOrAdjustTransaction.

STAGING_URL : https://sandbox-rest.avatax.com/api/v2

PROD_URL : https://rest.avatax.com/api/v2

1. CreateOrAdjustTransaction

Route: POST <PROD|STAGING_URL>/transactions/createoradjust?$include=Lines

1.1 CreateTransaction Structure - Avalara Tax API

Parameter	Type	Description	Value

Parameter	Type	Description	Value
code	string	Unique transaction code	Dynamic: `order.ID` - Order identifier created in OneStock
commit	bool	Indicates if the transaction should be committed	Dynamic: Based on `input.commit`
companyCode	string	Avalara company code	Configuration: Sales channel : `avalara.company_code`
currencyCode	string	Currency code (ex: "EUR")	Dynamic: `order.PricingDetails.Currency` - Base currency for this order. Three-character currency code compliant with ISO 4217
customerCode	string	Unique customer code	Dynamic: `order.Customer.ID` if found or `order.Customer.Email` instead or `order.ID` as fallback - Customer identifier for the transaction
date	string	Transaction date	Dynamic: Current date in YYYY-MM-DD format
entityUseCode	string	Tax exemption code	Dynamic: Tax exemption code if applicable for the customer
lines	[]*LineItem	List of transaction items	Dynamic: Array of `LineItem` objects containing details of each item and shipping fees
type	TransactionType	Transaction type	Dynamic: `SalesOrder`, `SalesInvoice`, `ReturnOrder`, `ReturnInvoice` depending on the operation type
userDefinedFields	[]UserDefinedField	Custom fields	Dynamic: User-defined fields to store additional information
addresses	*Addresses	Shipping and billing addresses	Dynamic: `Addresses` object containing `ShipFrom`, `ShipTo` or `SingleLocation` depending on delivery type
taxOverride	*TaxOverride	Tax override	Dynamic: Used for refunds with `TaxDate` corresponding to the original transaction creation date

1.2 Sub-structure Details

LineItem

Parameter	Type	Description	Value

Parameter	Type	Description	Value
number	string	Unique line number	Dynamic: `domain.LineIDFromIndexRanges()` for items lines, `"SF_<Number_X>"` for shipping fees
amount	float64	Line amount	Dynamic: Item price or shipping fees
description	string	Item description	Dynamic: `item.Description` or `"Shipping Fees"` for shipping fees
itemCode	string	Item code	Dynamic: `line.ItemID` or Configuration: `shippingFeesTaxInformation.ShippingItemCode` where shippingFeesTaxInformation is calculated from config `avalara.default_item_code` or `avalara.shipping_tax_information_by_delivery_type.<delivery_type>.item_code`
taxCode	string	Tax code	Dynamic: `item.TaxCode` or Configuration: `shippingFeesTaxInformation.ShippingTaxCode` where shippingFeesTaxInformation is calculated from config `avalara.default_tax_code` or `avalara.shipping_tax_information_by_delivery_type.<delivery_type>.tax_code`
hsCode	string	Harmonized code	Dynamic: `item.HSCode` - Customs classification code
taxIncluded	bool	Tax included in price	Dynamic: `input.includedInPrice` - Indicates if tax is included in the price
quantity	int64	Quantity	Dynamic: `line.Quantity` or `1` for shipping fees
addresses	*Addresses	Line-specific addresses	Dynamic: `SingleLocation` if StraightFulfilled, `ShipFrom`, `ShipTo` otherwise
userDefinedFields	[]UserDefinedField	Line custom fields	Dynamic: `UDF50` for index ranges, `UDF49` to indicate if the line is about shipping fee, `UDF48` for shipping fee type

Addresses

Parameter	Type	Description	Value

Parameter	Type	Description	Value
shipFrom	*AddressLocation	Shipping address	Dynamic: Origin address of the delivery
shipTo	*AddressLocation	Delivery address	Dynamic: Destination address of the delivery
singleLocation	*AddressLocation	Single address	Dynamic: Used for direct deliveries (StraightFulfilled)

AddressLocation

Parameter	Type	Description	Value

Parameter	Type	Description	Value
city	string	City	Dynamic: `address.City`
country	string	Country code	Dynamic: `address.Regions["country"].Code`
line1	string	Address line 1	Dynamic: `address.Lines[0]`
line2	string	Address line 2	Dynamic: `address.Lines[1]` (if available)
line3	string	Address line 3	Dynamic: `address.Lines[2]` (if available)
locationCode	string	Avalara location code	Configuration: Endpoint - Location code configured in Avalara
postalCode	string	Postal code	Dynamic: `address.ZipCode`
region	string	Region/state code	Dynamic: `address.Regions["province"].Code` (if available)

2. Estimation

Using CreateOrAdjustTransaction plus some specific parameters:

2.1 Estimation - Creation

Parameter	Type	Description	Value

Parameter	Type	Description	Value
commit	bool	Transaction commit status	Hard-coded: `false` - Estimation transactions are never committed
type	TransactionType	Transaction type	Hard-coded: `SalesOrder` - Always uses SalesOrder for estimations
adjustmentDescription	string	Adjustment description	Hard-coded: `""` - Empty string for new estimations

2.2 Estimation - Refund

Parameter	Type	Description	Value

Parameter	Type	Description	Value
commit	bool	Transaction commit status	Hard-coded: `true` - Refund estimation transactions are committed
type	TransactionType	Transaction type	Hard-coded: `ReturnOrder` - Always uses ReturnOrder for refund estimations
adjustmentDescription	string	Adjustment description	Hard-coded: `""` - Empty string for refund estimations
taxOverride	*TaxOverride	Tax override	Dynamic: Override some properties from original transaction creation

TaxOverride

Parameter	Type	Description	Value

Parameter	Type	Description	Value
taxDate	string	Tax date	Dynamic: Original transaction creation date in YYYY-MM-DD format

3. Create

Using CreateOrAdjustTransaction plus some specific parameters:

Parameter	Type	Description	Value

Parameter	Type	Description	Value
commit	bool	Transaction commit status	Dynamic: Based on the `input.commit`
type	TransactionType	Transaction type	Dynamic: `SalesInvoice` by default, `SalesOrder` if `forceSalesOrder` is true
adjustmentDescription	string	Adjustment description	Hard-coded: `""` - Empty string for new transactions

4. Refresh

Using CreateOrAdjustTransaction plus some specific parameters:

Parameter	Type	Description	Value

Parameter	Type	Description	Value
commit	bool	Transaction commit status	Dynamic: Based on the `input.commit`
type	TransactionType	Transaction type	Hard-coded: `SalesInvoice` - Always uses SalesInvoice for refresh/adjust
adjustmentDescription	string	Adjustment description	Hard-coded: `"OneStock refresh"` - Fixed description for refresh operations

5. Refund

Using CreateOrAdjustTransaction plus some specific parameters:

Parameter	Type	Description	Value

Parameter	Type	Description	Value
commit	bool	Transaction commit status	Hard-coded: `true` - Refund transactions are always committed
type	TransactionType	Transaction type	Dynamic: `ReturnInvoice` by default, `ReturnOrder` if `forceSalesOrder` is true
adjustmentDescription	string	Adjustment description

Avalara - Technical documentation

C4 diagrams

Context

OIS

Web

Authentication

Specific header

Configuration

0. Before starting

1. CreateOrAdjustTransaction

1.1 CreateTransaction Structure - Avalara Tax API

1.2 Sub-structure Details

LineItem

Addresses

AddressLocation

2. Estimation

2.1 Estimation - Creation

2.2 Estimation - Refund

TaxOverride

3. Create

4. Refresh

5. Refund