Transactions

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_quantity is set and UnitOfMeasure is a volume unit (ML, OZ, GRM, GAL, or GLL), the value is the checkout quantity multiplied by ate_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.

Did you find this article useful?