Orders

Manage AvaTax Excise orders

Use the AvaTax Excise order tools after a BigCommerce order has been placed. The order extension lets you:

- View the AvaTax Excise transaction linked to the order and its status.
- Commit or void the transaction.
- Apply BigCommerce refunds to AvaTax Excise.
- Submit a manual adjustment to the transaction.

Complete Set up AvaTax Excise and Configure AvaTax Excise transaction fields before using this guide. The order must already have an AvaTax Excise transaction created from checkout tax calculation.

Open the Excise order extension

  1. In BigCommerce, open Orders.
  2. Select the order you want to review.
  3. Open the Excise order adjustment panel.

The panel loads the order automatically. To load the latest values again, click Refresh in the Avalara Excise transaction card. This also discards changes that you have not submitted.

The panel has these cards:

Card Contents
Avalara Excise transaction Order ID, line count, transaction code, status, and the Commit and Void buttons.
Refunds BigCommerce refunds for the order, and the Apply to Avalara Excise button.
Manual adjustment Editable fields for an adjustment, and the Submit adjustment button.
Last response The response to the last action.

The panel works only while Avalara Product is set to AvaTax Excise. If the store uses a different Avalara product, the panel shows an error.

The panel fills its fields from the current BigCommerce order, the current product tax properties and custom fields, the transaction values that the app saved, and the store’s Avalara settings. The transaction status is read from AvaTax Excise. Changes made directly in AvaTax Excise to other values do not appear in the panel.

Confirm the transaction code

The Transaction code (ATE) is the AvaTax Excise transaction ID linked to the BigCommerce order. The app reads this value from the order’s tax data created during checkout. 

If the transaction code is present, the order is ready for AvaTax Excise actions. If the transaction code is missing, the panel shows an adjustment unavailable message.

Next to the transaction code, a status badge shows Committed, Voided, or Not committed:

Status Meaning
Not committed The transaction is not included in your Excise returns yet. Commit it when the order is final.
Committed The transaction is included in your Excise returns.
Voided The transaction is left out of your Excise returns and can no longer be changed.

When no transaction code is found

The Commit and Void buttons and the Manual adjustment card do not appear.

Check the following:

Check What to confirm
AvaTax Excise was enabled at checkout The store was configured with Avalara Product = AvaTax Excise when the order was placed.
AvaTax Excise is still enabled Avalara Product is still set to AvaTax Excise.
Tax calculation ran during checkout The checkout received an AvaTax Excise tax result.
Product was taxable The order included taxable tobacco, nicotine, vape, or Excise products.
Credentials and company code are valid AvaTax Excise requests were accepted during checkout.

If the order was placed before AvaTax Excise was configured, create a new test order after setup and check the panel again.

Commit a transaction

Use Commit when the AvaTax Excise transaction should be finalized for Avalara processing and reporting.

If Commit Transactions on checkout completion is on in the Avalara settings, the app commits the transaction when the order is placed. In that case, the panel already shows Committed.

  1. Open the order extension.
  2. Confirm the Transaction code is present.
  3. Click Commit.
  4. Confirm the action when prompted.
  5. Review the response shown in the panel.

Commit is disabled when the transaction is already committed or voided.

Commit usually cannot be undone from the order extension. Confirm your Avalara workflow before committing production transactions.

Void a transaction

Use Void when the AvaTax Excise transaction should no longer be included in Avalara processing.

If Void Transactions on order cancellation is on in the Avalara settings, the app voids the transaction when the order status changes to Cancelled.

  1. Open the order extension.
  2. Confirm the Transaction code is present.
  3. Click Void.
  4. Confirm the action when prompted.
  5. Review the response shown in the panel.

You can void a committed transaction. Void is disabled only when the transaction is already voided.

Void usually cannot be undone from the order extension. Confirm that the transaction should be voided before continuing. After you void a transaction, the adjustment fields become read-only.

Apply a refund

When you refund products in BigCommerce, AvaTax Excise does not change automatically. Use the Refunds card to send each refund to AvaTax Excise.

For refunded products, use Refunds. Do not use a manual adjustment.

What the app sends

For each refund, the app creates and commits a separate return document in AvaTax Excise. The original transaction does not change.

Return value Source
Transaction type ReturnInvoice.
Invoice number The original invoice number followed by -R and the refund’s position, for example 1042-R2. If this is longer than 12 characters, the app uses a generated code that starts with R.
Invoice date The date of the BigCommerce refund.
Effective date The invoice date of the original transaction, so the return uses the original tax rates.
Lines One line for each refunded product, copied from the original transaction and scaled to the refunded quantity. BilledUnits is negative. All other units and prices are positive.
Description The original invoice number, the BigCommerce order and refund IDs, and the refund reason.

Apply a refund

  1. Open the order extension.
  2. Confirm that the transaction status is Committed. You cannot apply a refund to a transaction that is not committed or is voided.
  3. In Refunds, find the refund.
  4. Click Apply to Avalara Excise.
  5. Confirm the action when prompted.
  6. Review the response shown in the panel.

When the refund is applied, the card shows the return invoice number and the return document code:

Refund status

Status Meaning
pending The refund has not been sent to AvaTax Excise.
processing The app is sending the refund.
succeeded The return was created and committed.
failed The last attempt failed. The card shows the error. Click Retry Avalara Excise to try again.
handled by earlier sync An earlier version of the app already sent this refund as a return. It cannot be applied again.

It is safe to apply a refund again after a failure. The app updates the same return document and does not create a second one.

Refund rules

  • Apply refunds in order, oldest first. A later refund stays blocked until the earlier refunds succeed.
  • A refund must contain products. Refunds of other items, such as fees, cannot be applied.
  • If Include Shipping in Tax Request is on, refunds that include shipping cannot be applied. If it is off, the app ignores the shipping part of the refund.
  • The refunded quantity cannot be more than the quantity not yet refunded.
  • After a refund succeeds, the Manual adjustment card uses the remaining quantity for each product.

If a refund cannot be applied, the card shows the reason under the refund.

Submit an adjustment

Use Submit adjustment when you need to send a new version of an existing order transaction to AvaTax Excise.

  1. Open the order extension.
  2. Confirm the Transaction code is present.
  3. In Manual adjustment, review or update the adjustment reason, description, and overrides.
  4. Review the Transaction document fields and the line values.
  5. Click Submit adjustment.
  6. Review the response shown in the panel.

After a successful adjustment, the panel loads the latest values again.

The app sends an AvaTax Excise CreateOrAdjust request with:

  • The existing transaction code linked from the order.
  • An adjustment reason.
  • An adjustment description.
  • A new version of the transaction built from the BigCommerce order and the values in the panel.

The new version of the transaction contains:

  • One line for each order product, using the quantity not yet refunded. Shipping and handling lines are not included.
  • The origin address from the company address in the Avalara settings.
  • The destination address from the order’s shipping address.
  • The order’s currency.

Adjustment reason and description

Each adjustment includes a reason and description.

Field Description
Adjustment reason AvaTax Excise reason code for the adjustment. Starts with the default reason in the Avalara settings, or Other.
Adjustment description Short description of the adjustment. Maximum 256 characters. Starts with the default description in the Avalara settings, or BigCommerce Excise Tax Request.

Available reason codes include:

  • NotAdjusted
  • SourcingIssue
  • ReconciledWithGeneralLedger
  • ExemptCertApplied
  • PriceAdjusted
  • ProductReturned
  • ProductExchanged
  • BadDebt
  • Other
  • Offline

If you are not sure which reason to use, confirm with your Avalara implementation team.

Seller, buyer, transaction type, and title transfer overrides

The order extension starts with the default values from Avalara settings. You can override them for the adjustment before submitting.

Field Description
Seller override Seller business entity ID sent to AvaTax Excise.
Buyer override Buyer business entity ID sent to AvaTax Excise.
Transaction type override Transaction type, such as WHOLESALE, RETAIL, or DIRECT.
Title transfer code override ORIG or DEST.

These changes apply only to the adjustment being submitted from this order screen. They do not update the store’s default Avalara settings.

Transaction document fields

The Transaction document section controls document-level values on the new version of the transaction.

Field Description Starts with
Effective date Date AvaTax Excise should use for tax rate lookup. The BigCommerce order date.
Invoice date Invoice date sent to AvaTax Excise. The BigCommerce order date.
Invoice number Invoice number sent to AvaTax Excise. Maximum 12 characters. The BigCommerce order ID.
Document entity use code Optional document-level sales/use exemption code. Empty.
AvaTax transaction type AvaTax transaction type, such as SalesInvoice. SalesInvoice.
Transaction code (ATE) Existing linked transaction code. Read-only. Not applicable.

Checkout sets the invoice number to a code that the app generates. The invoice number in this section starts with the order ID, so an adjustment changes the transaction’s invoice number unless you enter the original invoice number.

The document entity use code and the document custom values start empty. They do not contain the values sent at checkout. Enter them again if the transaction needs them.

Use YYYY-MM-DD date values.

Document custom values

Open Document custom strings / numerics to send additional AvaTax Excise document values.

Field group Maps to
Header custom string 1-10 AvaTax Excise root CustomString1 through CustomString10. Maximum 256 characters.
Header custom numeric 1-10 AvaTax Excise root CustomNumeric1 through CustomNumeric10. Must be numbers.

Use these fields only when Avalara has instructed you to send additional document-level values for your tax scenario.

Line fields

The panel shows one row for each order product. Click a row to open its fields.

Field Description Starts with
Line name, SKU, and ID BigCommerce product name, SKU, and order product ID. Read-only. Not applicable.
Net Net quantity sent to AvaTax Excise. The quantity not yet refunded. For volume units of measure, this is multiplied by ate_unit_quantity.
Gross Gross quantity sent to AvaTax Excise. Same as Net.
Billed Billed quantity sent to AvaTax Excise. Same as Net.
Line entity use Optional line-level entity use code. The value last sent to AvaTax Excise, or the product tax property or custom field.
Sale address 1 Sale address line 1. The value last sent to AvaTax Excise, or the order’s shipping address.
Sale city Sale city. The value last sent to AvaTax Excise, or the order’s shipping address.
Custom 1-3 Line CustomString4 through CustomString6. CustomString1 through CustomString3 are reserved for the order product ID, name, and SKU. The value last sent to AvaTax Excise, or the product tax properties ate_custom_string_1 through ate_custom_string_3.

The other sale address values come from the order’s shipping address. Product code, unit of measure, and alternate unit price are not shown. They come from the transaction last sent to AvaTax Excise, or from the product tax properties and custom fields.

For tobacco, nicotine, and vape products, confirm the correct units and product treatment with Avalara before submitting an adjustment.

Read-only BigCommerce order data

The panel includes a BigCommerce order (read-only) section. These values come from BigCommerce and help you confirm that you are adjusting the correct order.

The read-only section may include:

  • Order ID.
  • Line count.
  • AvaTax Excise transaction code.
  • Transaction code source.

Changing editable Avalara fields cannot change the original BigCommerce order details.

Review the response

After commit, void, or adjustment, the panel shows Last response.

Use this response to confirm whether AvaTax Excise accepted the request. If Avalara returns an error, review the message and update the relevant order, customer, product, or AvaTax Excise configuration before trying again.

Common issues

Problem What to check
Commit or Void is disabled Confirm a transaction code exists on the order.
Adjustment unavailable Confirm the order was created after AvaTax Excise checkout tax was configured.
Company mapping error Confirm the Avalara company code and origin address are saved in Avalara settings.
Buyer or seller is wrong Update the order override fields or the store defaults in Avalara settings.
Unit values are rejected Confirm net, gross, and billed units match the product setup expected by Avalara.
Transaction type is rejected Confirm the value is valid for your AvaTax Excise tobacco, nicotine, or vape scenario.
Date is rejected Use YYYY-MM-DD format.
Adjustment succeeds but BigCommerce order is unchanged Adjustment values are sent to Avalara only; they do not edit the BigCommerce order record.

Did you find this article useful?