Entity use codes

Element type: Required

Endpoints/models used: ListEntityUseCodes, CreateTransactionModel

Entity use codes are 1 method for maintaining tax-exempt customer transactions. When entering transactions with an entity use code, AvaTax will exempt the transaction as long as the code is valid for the customer and region where the transaction takes place.

This functionality can be added at the document or line level, depending on your system’s need. Review the standard codes, but users are able to create custom codes as well. It’s best to manage this value in your application’s customer record and pass it to AvaTax at either the document or line level, whichever is applicable.

Entity use codes are displayed in the UI 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 doesn’t have a custom entity use code.

Here’s how to find the values and put them into your transaction. First, call the ListEntityUseCodes API. The code field is the value that you’ll use, and the field name is the description you’ll show to the customer. You can either show “code - name”, like "A - FEDERAL GOV", or you can just show the name field.

View example:

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

If the customer is exempt and makes a purchase, put that value in the entityUseCode field in the CreateTransactionModel:

View example:

{
    "type": "SalesInvoice",
    "companyCode": "DEFAULT",
    "date": "2024-08-16",
    ...
    "entityUseCode": "A",
    ...
}

If the customer isn’t exempt, omit the entityUseCode field entirely, or set its value to null.