# Transaction FAQs

Source: https://developer.avalara.com/marketplace-integration-guide/transactions/transaction-faqs/

This section provides answers to common questions that users face when creating transactions.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)Can I exempt transactions in Canada?](javascript:void\(0\);)

You can exempt transactions in Canada using exempt reasons specific to Canadian Provinces. Refer to the [Exempt reason matrix for the US and Canada](https://knowledge.avalara.com/bundle/dqa1657870670369_dqa1657870670369/page/Exempt_reason_matrix_for_the_U.S._and_Canada_entity_use_code_list.html) Knowledge Center topic for more information. After you understand these use codes, you have a couple of options:

-   Create a product taxability tax rule making the tax codes of the products nontaxable in Canada and in the province.

-   Create an exempt entity tax rule making the entity use code of your choice tax exempt in Canada and in the province.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)Can I include lines with a zero amount in my transactions](javascript:void\(0\);)

Yes

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)Can I provide custom exempt reason codes?](javascript:void\(0\);)

Yes. You can create custom entity use codes as part of a custom tax rule. Refer to the [TaxRuleModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/TaxRuleModel/) API for more information. Your integration must be able to support custom tax rules entered by a user.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)Can item mapping be completed at the category level?](javascript:void\(0\);)

Yes, if your platform supports grouping of like items.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)Can my integration provide invoice history via a data import process?](javascript:void\(0\);)

AvaTax provides a [batch](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Batches/CreateTransactionBatch/) endpoint to pass a file that includes batches of transactions. When using this endpoint, be sure to review the [Guidelines for importing tax data into the AvaTax](https://knowledge.avalara.com/bundle/dqa1657870670369_dqa1657870670369/page/Guidelines_for_importing_tax_data_into_AvaTax.html) and [Import transaction template guidelines](https://knowledge.avalara.com/bundle/dqa1657870670369_dqa1657870670369/page/Import_transactions_template_guidelines_1.html) Knowledge Center articles. In addition, keep in mind that the maximum content length of the request body is limited to 28.6 MB.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)Do I have to add a line to represent freight on the transaction?](javascript:void\(0\);)

Yes. In AvaTax, shipping and handling charges are line items that are mapped to product codes just like any item that you ship. More information is available in the earlier [Nonstandard item transactions in AvaTax](marketplace-integration-guide/transactions/non-standard-item-transactions/nonstandard-item-transactions-in-avatax.htm) topic and in the [Understanding freight taxability](https://knowledge.avalara.com/bundle/dqa1657870670369_dqa1657870670369/page/Understanding_freight_taxability.html) Knowledge Center topic.

It's also possible to have multiple freight lines on a transaction that include different addresses. For example, one item may be shipping to CA and another to NY. AvaTax will look for a freight line, and based on the address of that line will group those items together. So, if a freight line item is shipping to CA, AvaTax will bundle line items with that same CA address and use that information for determination.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)For Canadian transactions, can AvaTax display GST and PST on invoices?](javascript:void\(0\);)

By default, AvaTax always returns PST and GST as separate amounts in the response. However, AvaTax doesn't maintain content for provinces that use HST. If you require HST information on invoices, you should create a [custom tax rule](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/TaxRules/CreateTaxRules/) to consolidate those amounts in the response.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)How can I get a list of AvaTax tax codes?](javascript:void\(0\);)

Avalara provides a [tax code search tool](https://taxcode.avatax.avalara.com/) to help you find the codes that determine the taxability of the goods and services you sell. You can also run the [ListTaxCodes](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Definitions/ListTaxCodes/) API to retrieve the full list of Avalara\-supported tax codes.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)How can I get offline tax rates?](javascript:void\(0\);)

If you need to calculate tax offline, there are a couple of ways to retrieve offline tax rates using the AvaTax TaxContent APIs. The method to use varies depending on whether you're creating single location transactions or transactions with `shipFrom` and `shipTo` addresses.

**Single-location transactions:**  

For single-location transactions, use the [BuildTaxContentFileForLocation](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/TaxContent/BuildTaxContentFileForLocation/) API to build a tax content file that includes a matrix of taxes that are charged for the items you sell at a specific location. This is built by looking up the tax profile for your location and your items and then calculating taxes for each in turn. To include a custom tax code in this tax content file, first create the custom tax code using [CreateTaxCodes](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/TaxCodes/CreateTaxCodes/) to create the custom tax code, then use [CreateItems](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Items/CreateItems/) to create an item that uses the custom tax code.

Because tax rates can change based on decisions made by a variety of tax authorities, we recommend that users of this tax content API download new data every day. Many tax authorities may finalize decisions on tax changes at unexpected times and may make changes in response to legal issues or governmental priorities. Any tax content downloaded for future time periods is subject to change if tax rates or tax laws change.

When generating offline tax for single-location transactions, consider the following:

-   The BuildTaxContentFileForLocation API doesn't work for Tennessee tax holiday scenarios.

-   If you want to create a single TaxContent file for all of your locations, use the [BuildTaxContentFile](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/TaxContent/BuildTaxContentFile/) API.

Multiaddress locations:

If you need to calculate tax for transactions that require shipment of goods, use the [DownloadTaxRatesByZipCode](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/TaxContent/DownloadTaxRatesByZipCode/) API. This downloads a CSV file containing all five-digit postal codes in the United States and their sales and use tax rates for tangible personal property. This rates file is intended to be used as a default for tax calculation when your software can’t call the [CreateTransaction](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Transactions/CreateTransaction/) API call. When using this file, your software will be unable to handle complex tax rules. If you use this file to provide default tax rates, make sure to reconcile the actual transaction and determine the difference between the estimated general tax rate and the final transaction tax.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)How can I issue a credit or adjustment when sales tax has already been applied?](javascript:void\(0\);)

Review the [Add or import tax-only credits](https://knowledge.avalara.com/bundle/dqa1657870670369_dqa1657870670369/page/Add_or_import_tax-only_credits.html) in the Avalara Knowledge Center.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)How can I use a single-use exemption in AvaTax?](javascript:void\(0\);)

The key to matching a certificate created in AvaTax with your integration is: 

-   Passing the `customerCode` (which is required), and

-   Matching the customer ID you're passing in the CreateTransaction request to the way that the exemption was setup in AvaTax.

If you set up the exemption as a "Single Use Exemption", AvaTax expects that you’ll also pass a `purchaseOrderNo` in the request.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)How can I utilize drop shipping?](javascript:void\(0\);)

Contact [Partner Central](https://avalara.zinfi.net/concierge/ucm/#/CountryLanguage?redirect=%2Fcms%2FHome) if your platform supports drop shipping.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)How do I discount a transaction?](javascript:void\(0\);)

There are several options for discounting transactions that are described in the [Discount a transaction](marketplace-integration-guide/transactions/discounts-and-overrides/discount-a-transaction.htm) topic. In general, keep the following guidelines in mind.

-   Merchants discounting a retail price, either for a specific item or in general for a particular order/invoice, simply reduce the pretax amount to be passed to AvaTax.

    -   Handle line-level/item-specific discounts by reducing the retail price of the item by the discount and passing that value in the transaction's `amount` field.

    -   Handle document-level/order-invoice discounts using the document `discount` field in the transaction request.

-   Merchants providing a "buy one/get one free" type scenario don't typically have a sales tax calculation impact. The discount merely reduces the pretax amount to be passed to AvaTax.

    -   Certain "buy one/get one free" scenarios may require the merchant to self-assess, accrue, and pay (consumer) use tax on the item given away at no cost, as the merchant is considered the consumer of the article. This doesn't change the CreateTransaction call to calculate sales tax on the order/invoice.

-   Manufacturer’s/third-party coupons refer to coupons provided by the manufacturer or other third party and not the merchant itself. These will often have special tax treatment. When the merchant accepts the coupon, the call to the AvaTax should identify the coupon discount as a unique line item with a negative value and include the appropriate AvaTax tax code indicating a third-party coupon.

    -   These types of coupons often reimburse the merchant for the discount. Certain states interpret this as a form of cash payment, requiring the buyer to pay sales tax on the full amount of the coupon-related item.

    -   If there's an actual third-party/manufacturer’s coupon associated with the reduction in price, pass it as a line item with a negative value, and associate it with Tax Code `OC030000`.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)How do I handle bundled items?](javascript:void\(0\);)

Bundled items include a single item that is made up of several individual items (for example, a gift basket). To tax bundled items correctly, you have to upload a spreadsheet of the individual items included in that bundle. AvaTax will preprocess the transaction. When a bundled item is included on a transaction line, AvaTax replaces it with the individual items included in the bundle and will calculate tax based on each of those individual items.)

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)How do I handle product exemptions?](javascript:void\(0\);)

Products/items are exempt based on their tax code. You can create custom tax codes and apply an entity use code to that tax code. That custom tax code can then be applied to an item in AvaTax. Refer to the [TaxCodeModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/TaxCodeModel/) API for more information.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)My transaction includes a negative quantity. Why is the calculated tax positive?](javascript:void\(0\);)

When creating transactions, the `quantity` value must be positive. If you attempt to pass a negative value, AvaTax will treat it as positive. If you're attempting to refund an item, pass a negative value for the `amount`. AvaTax will treat that amount as negative when calculating tax.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)What are the usage terms, and how is usage billed?](javascript:void\(0\);)

Review the [AvaTax supplemental terms](https://legal.avalara.com/product-terms.html#avatax) for this information.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)What's the address hierarchy between the document and line level?](javascript:void\(0\);)

You can enter addresses at the line level or the document level. If you pass an address at the line level, that address will apply to that line. If you pass an address at the document level, that address applies to all lines in the document. If a document consists of addresses at the line level and also at the document level, the line-level addresses will take precedence over the document-level addresses.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)What's the difference between a customer code and a vendor code?](javascript:void\(0\);)

The use of vendor vs customer is contextual based on the transaction type. Vendor IDs are for Purchase transaction types; customer IDs are for Sales and Return transaction types.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)What's the difference between totalTax and totalTaxCalculated in a transaction response?](javascript:void\(0\);)

`totalTax` indicates the sum of all tax amounts for all lines. `totalTaxCalculated` indicates the total tax calculated by AvaTax. This is usually the same as the `totalTax`, except when a tax override amount is specified. `totalTaxCalculated` is for informational purposes; `totalTax` will still be used for reporting.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)What's the exemption hierarchy?](javascript:void\(0\);)

-   [Exemption numbers](marketplace-integration-guide/transactions/exemptions/exemption-numbers.htm) take precedence over [Entity use codes](marketplace-integration-guide/transactions/exemptions/entity-use-codes.htm).

-   If you have a transaction that exempts a customer, for example, as a reseller, but that customer is already configured as an exempt manufacturing customer in the customer record, AvaTax will use the document level exempt reason over the reason in the customer record.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)What is the hierarchy between street level and longitude/latitude level information in addresses?](javascript:void\(0\);)

If you provide latitude and longitude information for an address along with line, city, region, country and postal code information, AvaTax will only use the latitude and longitude values. If you provide either latitude or longitude information but not both, AvaTax will then use the line, city, region, country, and postal code information for the addresses.

Ensure that you have the correct latitude/longitude information for an address when including these in your API calls.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)Why am I seeing an \\"EntityNotFoundError\\",\\"message\\":\\"Company not found.\\" error message?](javascript:void\(0\);)

AvaTax returns this message when the `companyCode` in your request doesn't exist in the account that you're making the CreateTransaction request against.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)Why does the tax in my ERP not match the tax in my ecommerce integration?](javascript:void\(0\);)

This is likely caused by a mismatch of tax codes. Make sure the tax codes used in your ERP are the same as your tax codes in your ecommerce integration. For example if you use a shipping tax code of "fob destination" in your ecommerce integration, but your ERP refers to this as "fob origin,", then your tax calculation will differ on shipping.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)Why is AvaTax collecting tax for a customer that is set up as exempt?](javascript:void\(0\);)

This is likely due to an error in the `customerCode`. When creating a transaction for an exempt customer, the `customerCode` must match exactly the customer ID of the certificate that was created during the exemption setup. If these don't match exactly, then AvaTax will return tax in the transaction.

[![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)Is it normal to see multiple tax entries for one jurisdiction?](javascript:void\(0\);)

This is expected behavior in Avalara’s tax engine. Tax is calculated per line item, and each jurisdiction can apply multiple rates or components depending on the nature of the item, special rules, or thresholds.

We recommend that you don't assume a transaction will contain only one tax entry per jurisdiction. Your integration should be able to handle multiple entries for the same. And never overwrite or discard entries with matching `jurisCod`e or `jurisName`.

### Examples

**Phoenix, AZ: Two city-level taxes for the same jurisdiction**

In this example, Phoenix city appears twice in the tax details:

-   One with a 2.8% rate on most of the item value,

-   Another with a 2.0% rate on a separate portion of the value.

**Request**:

```
      "lineAmount": 15000,	"city": "Phoenix",	"region": "AZ"
```

**Response**:

```
"details": [{      "jurisName": "PHOENIX",       "rate": 0.028,	"taxableAmount": 13886,	"tax": 388.81   },   {	"jurisName": "PHOENIX",	"rate": 0.02,	"taxableAmount": 1114,	"tax": 22.28   }]
```

**Note**: These examples are partial snippets to illustrate how multiple entries appear. They are not complete API request or response payloads.

These appear as separate line items, even though both are under the same city jurisdiction.

**Davidson County, TN: Multiple taxes from the same county**

This transaction has two county-level entries for Davidson County, TN:

-   A general rate of 2.25%

-   And a special school district tax of 0.5%

**Response**

```
"details": [ {	"jurisName": "DAVIDSON",	"taxSubTypeId": "S",	"rate": 0.0225	},	{	"jurisName": "DAVIDSON",	"taxSubTypeId": "SS",	"rate": 0.005	}				]
```

These are distinct tax components and must be reported separately even though they come from the same `jurisName`.

**Tennessee State: Single Article Tax Rule**

In Tennessee, high-value items may be subject to different tax treatments on portions of the value. This results in multiple entries for the state jurisdiction:

**Response**:

```
"details": [	{	"jurisName": "TENNESSEE",	"rate": 0.07,	"taxableAmount": 3300	},	{	"jurisName": "TENNESSEE",	"rate": 0.0275,	"taxableAmount": 1600,	"nonTaxableAmount": 1700	}]
```

This reflects the **Single Article Rule**, where part of the item value is taxed at a reduced rate.