Avalara Developer Network Developer avaTax

8.3 - Exemptions for Usage

In AvaTax, the EntityUseCode field provides information about how a transaction will be used by the customer, and information about the type of customer making the purchase. For example, a purchase made by the US federal government would be designated for government use, and it would generally be exempt or non-taxable for that specific use.

Entity Use Codes are generally displayed in the user interface of a connector as a dropdown, combo box, or selection element. This element uses the ListEntityUseCodes API to retrieve the list of available choices, and displays it as a list of values in a dropdown. The default value should be NULL, indicating that by default a transaction does not have a custom entity use code.

The value of the customer’s choice is placed in the customerUsageType field in the CreateTransctionModel element. Here’s how to find the values and put them into your transaction.

First, call the ListEntityUseCodes API. The field "code" is the value you will use, and the field "name" is the description you will show to the customer. You can either show “code - name”, like "A - FEDERAL GOV", or you can just show the name field.

{
    "@recordsetCount": 17,
    "value": [
        {
            "code": "A",
            "name": "FEDERAL GOV",
            "description": "",
            "validCountries": [
                "US"
            ]
        },
        {
            "code": "B",
            "name": "STATE GOV",
            "decription": "",
            "validCountries": [
                "US"
            ]
        },
    ]
}

If the customer makes a choice, put that value in the customerUsageType field on the CreateTransactionModel element:

{
    "type": "SalesInvoice",
    "companyCode": "DEFAULT",
    "date": "2017-06-16",
    ...
    "customerUsageType": "A",
    ...
}

If the customer does not make a choice, omit the customerUsageType element entirely, or set its value to null.

Since changing this value can make an entire transaction exempt, this field is not generally displayed when building a web storefront. Developers are encouraged instead to ask their customers for an exemption certificate or other documentation that can validate the claim that the customer is an exempt buyer.

Custom Integration

It’s suggested for a custom integration to implement entity use codes, if the application supports Tax Exempt sales.

Test Case - 8.3.1

Setup

  • Transactions sold with an EntityUseCode of "D" are considered sold for foreign diplomatic use.
  • In the United States, foreign diplomatic sales are legally exempt from sales taxes.
  • In your connector, create the following transaction:
    • Transaction Type: SalesInvoice
    • Transaction Code: Chapter-8-Test-2
    • Document Date: 2017-06-15
    • CompanyCode, Date set to reasonable default values.
    • CustomerCode Set to DEF
    • CustomerUsageType: D
    • Addresses:
      • SingleLocation
      • 100 Ravine Lane NE, Bainbridge Island, WA, 98110
    • Line #1:
      • Amount: 100
      • TaxCode: P0000000
  • Calculate tax for your transaction using AvaTax.

Assertions

  • The tax for line 1 should be $0.00.
  • The Taxable amount for line 1 should be $0.00.
  • The Exempt amount for line 1 should be $100.00.
  • 
    {
      "type": "SalesInvoice",
      "code": "Chapter-8-Test-2",
      "companyCode": "DEVGUIDE",
      "date": "2017-06-15",
      "customerCode": "TESTCUSTOMER",
      "customerUsageType": "D",
      "addresses": {
        "singleLocation": {
          "line1": "100 Ravine Lane NE",
          "city": "Bainbridge Island",
          "region": "WA",
          "country": "US",
          "postalCode": "98110"
        }
      },
      "lines": [
        {
          "number": "1",
          "amount": 100,
          "taxCode": "P0000000"
        }
      ]
    }