Configure AvaTax Excise transaction fields
Use this guide to configure the tobacco, nicotine, and vape transaction fields sent from BigCommerce to AvaTax Excise. These fields are used when the app calculates excise tax during checkout.
Complete Set up AvaTax Excise before using this guide. The store should already have Avalara Product set to AvaTax Excise, valid credentials, a company code, and default Excise transaction settings.

How checkout transactions are built
During checkout, BigCommerce sends a tax estimate request to the app. The app converts the cart, customer, addresses, product data, and BigCommerce tax properties into an AvaTax Excise transaction.
The app sends:
- One AvaTax Excise transaction for the checkout quote.
- One transaction line for each taxable product. The app does not send tax-exempt items, non-product lines (such as fees), or lines with a quantity of 0.
- A shipping line, product code
TAXFREIGHT, when Include Shipping in Tax Request is on and the shipping cost is more than 0. - A handling line when the handling cost is more than 0. There is no setting for this line.
- Document-level fields such as invoice date, effective date, seller, buyer, transaction type, and custom values.
- Line-level fields such as product code, unit of measure, units, sale address, entity use code, and custom values.

Field priority
Some values can be configured in more than one place. The app uses this priority:
| Priority | Source |
|---|---|
| 1 | BigCommerce tax properties on the customer, document, or product line. |
| 2 | Product custom fields or customer attributes created by the app, where supported. |
| 3 | Avalara settings in the app. |
| 4 | App fallback values, such as checkout quantity or today’s date. |
If the customer and the document have the same tax property, the app uses the customer value.
Buyer does not follow this priority. Refer to the Buyer row in the next table.
Use BigCommerce tax properties when you need values to vary by customer, product, or checkout context. Use app settings for defaults that apply broadly across the store.
Document-level transaction fields
Document-level fields apply to the whole AvaTax Excise transaction. This can be configured in App Setup.
| AvaTax Excise field | Where to configure it | Fallback |
|---|---|---|
EffectiveDate |
Tax property ate_effective_date on the customer or document. |
Today’s date. |
InvoiceDate |
Tax property ate_invoice_date on the customer or document. |
Today’s date. |
InvoiceNumber |
Tax property ate_invoice_number on the customer or document. Maximum 12 characters. The app removes extra characters. |
A 12-character code that the app generates from the store and the checkout quote. |
TransactionType |
Transaction Type in the Avalara settings. Get the correct value from Avalara. | DIRECT. |
TitleTransferCode |
Avalara Title Transfer Code in the Avalara settings: ORIG or DEST. |
DEST. |
Seller |
Seller ID in the Avalara settings. | Not sent. |
Buyer |
Default Buyer ID in the Avalara settings. If this is set and the customer has the attribute Avalara Custom ID, the app sends the Custom ID instead. | Not sent. If Default Buyer ID is empty, the app does not send a buyer, even when the customer has a Custom ID. |
UserTranId |
The checkout quote ID. | A new ID generated from the quote ID, if Avalara reports a duplicate transaction. |
EntityUseCode |
Tax property ate_entity_use_code on the customer or document, or customer attribute Avalara Customer Entity Use Code. |
Not sent. |
AvaTaxTransactionType |
Not available in the Avalara settings. | SalesInvoice. |
SourceSystem |
Source system (ATE) in the Avalara settings. | App default source system. |
DebugInd |
Environment in the Avalara settings. | N in a live environment, Y in all other environments. |
UserData |
Customer first and last name. | Guest Customer. |
UserReturnedValue |
Customer taxability_code from the BigCommerce tax request. |
Not sent. |
For date fields, use YYYY-MM-DD format. If a date is missing or not valid, the app uses today’s date.
Product line fields
Line-level fields apply to each product line sent to AvaTax Excise.
| AvaTax Excise field | Where to configure it | Fallback |
|---|---|---|
| ProductCode | Product tax property ate_product_code, or product custom field Avalara Product Code. | BigCommerce SKU or item reference. |
| UnitOfMeasure | Product tax property ate_unit_of_measure, or product custom field Avalara Unit of Measure. | Avalara settings unit of measure. |
| AlternateUnitPrice | Product tax property ate_alternate_unit_price, or product custom field Avalara Alternate Unit Price. | Product unit price. |
| UnitPrice | BigCommerce product price. | Product unit price. |
| Currency | BigCommerce checkout currency. | USD if unavailable. |
| EntityUseCode | Product tax property ate_entity_use_code, or product custom field Avalara Entity Use Code. | Blank. |
| Discounted | BigCommerce tax exempt flag. | false. |
For tobacco, nicotine, and vape products, confirm the correct product code, unit of measure, and unit quantities with Avalara. These fields often control which tax rules apply.
Document custom strings and numerics
AvaTax Excise supports custom document values. Use these fields when Avalara asks you to send additional document-level data for your tobacco, nicotine, or vape scenario.
| Tax property code | Maps to |
|---|---|
ate_document_custom_string_1 |
CustomString1 |
ate_document_custom_string_2 |
CustomString2 |
ate_document_custom_string_3 |
CustomString3 |
ate_document_custom_string_4 |
CustomString4 |
ate_document_custom_string_5 |
CustomString5 |
ate_document_custom_string_6 |
CustomString6 |
ate_document_custom_string_7 |
CustomString7 |
ate_document_custom_string_8 |
CustomString8 |
ate_document_custom_string_9 |
CustomString9 |
ate_document_custom_string_10 |
CustomString10 |
ate_document_custom_numeric_1 |
CustomNumeric1 |
ate_document_custom_numeric_2 |
CustomNumeric2 |
ate_document_custom_numeric_3 |
CustomNumeric3 |
ate_document_custom_numeric_4 |
CustomNumeric4 |
ate_document_custom_numeric_5 |
CustomNumeric5 |
ate_document_custom_numeric_6 |
CustomNumeric6 |
ate_document_custom_numeric_7 |
CustomNumeric7 |
ate_document_custom_numeric_8 |
CustomNumeric8 |
ate_document_custom_numeric_9 |
CustomNumeric9 |
ate_document_custom_numeric_10 |
CustomNumeric10 |
Custom string values are limited to 256 characters. Custom numeric values must be numbers.
Origin, destination, and sale addresses
Each AvaTax Excise line includes origin, destination, and sale address information.
| Address | Source |
|---|---|
| Origin address | Store company details configured in the Avalara settings and BigCommerce tax estimate document. |
| Destination address | Customer shipping address from checkout. |
Product line fields
Line-level fields apply to each product line sent to AvaTax Excise.
| AvaTax Excise field | Where to configure it | Fallback |
|---|---|---|
ProductCode |
Product tax property ate_product_code, or product custom field Avalara Product Code. Maximum 60 characters. |
BigCommerce SKU or item reference. |
UnitOfMeasure |
Product tax property ate_unit_of_measure, or product custom field Avalara Unit of Measure. |
Override Default Unit of Measure in the Avalara settings. If this is empty, GLL. |
AlternateUnitPrice |
Product tax property ate_alternate_unit_price, or product custom field Avalara Alternate Unit Price. |
UnitPrice. |
UnitPrice |
BigCommerce line amount divided by the checkout quantity, rounded to 2 decimals. | Not applicable. |
UnitQuantity |
Product tax property ate_unit_quantity. |
Checkout quantity. |
NetUnits, GrossUnits, BilledUnits |
Calculated by the app. Refer to Unit quantities. | Checkout quantity. |
Currency |
Not configurable. | Always USD. |
EntityUseCode |
Product tax property ate_entity_use_code, or product custom field Avalara Entity Use Code. The line does not use the document-level value. |
Blank. |
Discounted |
Not configurable. The app does not send tax-exempt items. | Always false. |
CustomId |
BigCommerce SKU or item reference. | Not applicable. |
For tobacco, nicotine, and vape products, confirm the correct product code, unit of measure, and unit quantities with Avalara. These fields often control which tax rules apply.
Product-level fields can be configured in an individual product's BigCommerce tax configuration:

Unit quantities
The app sets NetUnits, GrossUnits, and BilledUnits to the same value:
- If
ate_unit_quantityis set andUnitOfMeasureis a volume unit (ML,OZ,GRM,GAL, orGLL), the value is the checkout quantity multiplied byate_unit_quantity. - In all other cases, the value is the checkout quantity.
When the billed units are different from the checkout quantity, the app recalculates UnitPrice so that the line total does not change. The app also recalculates AlternateUnitPrice when it comes from UnitPrice.
Example: a customer buys 3 bottles of e-liquid. The product has ate_unit_of_measure = ML and ate_unit_quantity = 30. The app sends NetUnits, GrossUnits, and BilledUnits = 90.
Origin, destination, and sale addresses
Each AvaTax Excise line includes origin, destination, and sale address information.
| Address | Source |
|---|---|
| Origin address | The origin address in the BigCommerce tax estimate request. The address in the Avalara settings does not change it. |
| Destination address | Customer shipping address from checkout. |
| Sale address | Product tax properties when provided; otherwise the shipping address. |
Use these product tax properties to override the sale address:
| Tax property code | Maps to |
|---|---|
ate_sale_address1 |
SaleAddress1 |
ate_sale_address2 |
SaleAddress2 |
ate_sale_country_code |
SaleCountryCode |
ate_sale_jurisdiction |
SaleJurisdiction |
ate_sale_city |
SaleCity |
ate_sale_postal_code |
SalePostalCode |
If any sale address tax property is provided, the app uses those values and fills missing pieces from the shipping address.
Shipping and handling lines always use the shipping address as the sale address.
Line custom strings and numerics
AvaTax Excise supports custom values on each transaction line. The app reserves line CustomString1, CustomString2, and CustomString3 for BigCommerce line identity, SKU, and tax class information.
Use these product tax properties for additional custom line strings:
| Tax property code | Maps to |
|---|---|
ate_custom_string_1 |
CustomString4 |
ate_custom_string_2 |
CustomString5 |
ate_custom_string_3 |
CustomString6 |
ate_custom_string_4 |
CustomString7 |
ate_custom_string_5 |
CustomString8 |
ate_custom_string_6 |
CustomString9 |
ate_custom_string_7 |
CustomString10 |
Use these product tax properties for custom line numerics:
| Tax property code | Maps to |
|---|---|
ate_custom_numeric_1 |
CustomNumeric1 |
ate_custom_numeric_2 |
CustomNumeric2 |
ate_custom_numeric_3 |
CustomNumeric3 |
ate_custom_numeric_4 |
CustomNumeric4 |
ate_custom_numeric_5 |
CustomNumeric5 |
ate_custom_numeric_6 |
CustomNumeric6 |
ate_custom_numeric_7 |
CustomNumeric7 |
Custom string values are limited to 256 characters. Custom numeric values must be numbers.
Example tax properties
This example shows common tax properties for a tobacco, nicotine, or vape checkout.
Customer or document tax properties:
[
{ "code": "ate_effective_date", "value": "2026-06-01" },
{ "code": "ate_invoice_date", "value": "2026-06-01" },
{ "code": "ate_invoice_number", "value": "INV-10001" },
{ "code": "ate_entity_use_code", "value": "G" },
{ "code": "ate_document_custom_string_1", "value": "online-checkout" },
{ "code": "ate_document_custom_numeric_1", "value": "42" }
]
Product line tax properties:
[
{ "code": "ate_product_code", "value": "OTP-VAPE-CART" },
{ "code": "ate_unit_of_measure", "value": "ML" },
{ "code": "ate_unit_quantity", "value": "30" },
{ "code": "ate_alternate_unit_price", "value": "12.50" },
{ "code": "ate_custom_string_1", "value": "batch-A" },
{ "code": "ate_custom_numeric_1", "value": "1.5" }
]
Confirm exact product codes, units, and custom field meanings with Avalara before using them in production.
Common issues
| Problem | What to check |
|---|---|
| No tax is calculated | Confirm AvaTax Excise is selected, credentials pass, and the product is taxable. |
| Product code is rejected | Confirm the product code exists in AvaTax Excise. |
| Unit error from Avalara | Confirm ate_unit_of_measure and ate_unit_quantity match the product setup expected by Avalara. ate_unit_quantity changes the units only for volume units of measure. |
| Wrong buyer is sent | Confirm the customer Avalara Custom ID attribute. Also confirm that Default Buyer ID is set in the Avalara settings. If it is empty, the app sends no buyer. |
| Currency is wrong | The app always sends USD. |
| Entity exemption does not apply | Confirm the business entity exists in AvaTax Excise and the correct EntityUseCode, buyer, and business account/license data are configured. |
| Sale address is wrong | Confirm sale address tax properties or remove them so the shipping address fallback is used. |
| Custom values are missing | Confirm the tax property codes are spelled exactly as documented. |