Avalara Developer Network Developer avaTax

9.2 - Using Locations

To use the Location API in your connector, you must first identify what your system considers “locations”. Does your accounting system or tax platform store any of the following:

  • Addresses of warehouses
    • If your platform tracks warehouses, this would be a natural fit for locations in AvaTax. It's typically a short code that represents a specific warehouse that is managed within the platform itself.
  • Addresses of retail sales locations or field sales team members
    • Many platforms track locations where sales occur. These are also a good fit for locations.
  • Manual Data Entry
    • Avalara Certified connectors do not need to allow manual data entry for locations. If you would like to allow your users to enter locations for reporting purposes, we encourage you to provide a link to the Avalara AvaTax administration website where the customer can enter their locations directly.

If your platform stores information about locations and you wish to sync this data with AvaTax, you can use the CreateLocations API and the UpdateLocation API to store and maintain this data in AvaTax.

For the purposes of this chapter, let us create a new location within Texas, a state that sometimes requires location based reporting via the TX 01-115 form. Here’s how to use the CreateLocations API call to create a location within Texas:

Test Case - 9.2.1

Setup

  • Call the CreateLocations API call with the following information:
    • locationCode: TEXASWAREHOUSE
    • Description: "Texas Warehouse Chapter-9-Test-1"
    • addressTypeId: "Location"
    • addressCategoryId: "Warehouse"
    • Addresses:
      • 600 Congress Avenue, Austin, TX 78101
    • dbaName: Developer Guide Texas Warehouse
    • outletName: Texas Warehouse
    • registeredDate: Jan 1 2015

Assertions

  • Your location is created.
    • The location code matches the value you sent in.
    • The address matches the value you sent in.
  • [
      {
        "locationCode": "TEXASWAREHOUSE",
        "description": "Chapter-9-Test-1",
        "addressTypeId": "Location",
        "addressCategoryId": "MainOffice",
        "line1": "600 Congress Avenue",
        "city": "Austin",
        "region": "TX",
        "country": "US",
        "postalCode": "78101",
        "isDefault": false,
        "isRegistered": false,
        "dbaName": "Developer Guide Texas Warehouse",
        "outletName": "Texas Warehouse",
        "registeredDate": "2015-01-01T00:00:00"
      }
    ]
                    

Designating Transactions for a Reporting Location

For companies that must use location-based reporting, all transactions must be tied to either a reporting location code or to a default location.

You should allow your customer to choose a reporting location code using a drop-down or multi-select interface. You can retrieve a list of valid locations by calling the ListLocations API. You should present the friendly name of the location in the drop-down or multi-select box. If your user interface permits multi-line select boxes, please also include the address of the location. The user interface box for this drop-down or multi-select box should be “Reporting Location”. The default value of this box should be “None”.

If the user chooses “None”, you should set the reportingLocationCode value of your transaction to null. If the user selects a location, you should instead set the reportingLocationCode value to be the location code value from the location object.

Here’s how to create a transaction tied to a reporting location:

Test Case - 9.2.2

Setup

  • In your connector, create the following transaction:
    • Document Date: 2017-06-15
    • Customer Code: TESTCUSTOMER
    • reportingLocationCode: TEXASWAREHOUSE
    • Addresses:
      • SingleLocation
      • Send only the ZIP code 92612
    • Lines:
      • Amount 100
  • Calculate tax for your transaction using AvaTax.

Assertions

  • The created transaction should have reportingLocationCode = TEXASWAREHOUSE.
  • {
      "date": "2017-06-15",
      "customerCode": "TESTCUSTOMER",
      "reportingLocationCode": "TEXASWAREHOUSE",
      "addresses": {
        "singleLocation": {
          "postalCode": "92612"
        }
      },
      "lines": [
        {
          "amount": 100
        }
      ]
    }
                    

Shortcut for Addresses

Optionally, you can present your customers with a convenient shortcut for choosing addresses for their transactions. Similar to choosing a value for reporting location code, you can allow customers to chose an address location code as follows.

  • The customer can either hand-type an address, or they can select an existing location.
  • If the customer selects an existing location, the location's address will be used instead of whatever you type in.

Now that you’ve created a Locations successfully it’s time to use that Location data for reporting purposes on a transaction.

Test Case - 9.2.3

Setup

  • Create a transaction using the following settings:
    • Type: SalesInvoice
    • Code: Chapter-9-Test-3
    • Addresses:
      • Type: SingleLocation
      • LocationCode: TEXASWAREHOUSE
    • Lines:
      • 1 line with amount: 100
  • Create the transaction using your connector.

Assertions

  • The transaction is created as follows:
    • Address:
    • 600 Congress Avenue, Austin, TX 78101
  • {
      "type": "SalesInvoice",
      "code": "Chapter-9-Test-3",
      "companyCode": "DEVGUIDE",
      "date": "2017-06-15",
      "customerCode": "TESTCUSTOMER",
      "addresses": {
        "SingleLocation": {
          "locationCode": "TEXASWAREHOUSE"
        }
      },
      "lines": [
        {
          "amount": 100
        }
      ]
    }