Avalara Developer Network Developer avaTax

3.1 - Using Address Types

Address types are used to help determine tax for a given transaction in a given situation. A retail transaction and an eCommerce transaction are not that much different: they both use addresses, but while the retail location generally uses SingleLocation most eCommerce transactions will use the ShipFrom and ShipTo address types.

You can specify addresses at either the document level or the line level:

  • A transaction, as a whole, uses the document level addresses as a default. If a transaction does not have any addresses at the line level, each line will be assumed to use the addresses from the document level.
  • Line level addresses represent individual separate shipments. Any time you set a value on the addresses field on an invoice line, that line will ignore all document-level addresses

Using Document Level Addresses

When you record a single transaction and all invoice lines on the transaction have the same addresses, you only need to set your address values once at the root level of your transaction, no matter how many invoice lines you are calculating.

For this next test, let’s create a single transaction with multiple line items that were shipped from the same origin to the same destination. Here’s how to construct this transaction:

Let’s try building a transaction that uses two different addresses and a single line item:

Test Case 3.2.1 - Document Level Addresses

Setup

  • Your DEVGUIDE company should have nexus in California and Washington.
  • In your connector, create the following transactions
    • Document Type: SalesInvoice
    • Document Code: Chapter-3-Test-1
    • Company Code: DEVGUIDE
    • Document Date: 2017-06-15
    • Customer Code: TESTCUSTOMER
  • Addresses:
    • ShipFrom
      • 100 Ravine Lane NE, Bainbridge Island, WA 98110
    • ShipTo
      • 18300 Von Karman Ave, Irvine, CA 92612
  • Line #1:
    • Amount $100
  • Line #2:
    • Amount $50
  • Calculate tax for your transaction using AvaTax.

Assertions

  • The taxable amount should be $150.00 with a total tax amount of $11.63.
  • The document should be sourced in California with the following jurisdictions:
    • California State
    • Orange County
    • Orange County District Tax/Special Tax
    • Orange County Local Tax/Special Tax
  • {
      "type": "SalesInvoice",
      "code": "Chapter-3-Test-1",
      "companyCode": "DEVGUIDE",
      "date": "2017-06-15",
      "customerCode": "TESTCUSTOMER",
      "addresses": {
        "shipFrom": {
          "line1": "100 Ravine Lane NE",
          "city": "Bainbridge Island",
          "region": "WA",
          "country": "US",
          "postalCode": "98110"
        },
        "shipTo": {
          "line1": "18300 Von Karman Ave",
          "city": "Irvine",
          "region": "CA",
          "country": "US",
          "postalCode": "92612"
        }
      },
      "lines": [
        {
          "number": "1",
          "amount": 100
        },
        {
          "number": "2",
          "amount": 50
        }
      ]
    }
                    

Using Line Level Address Types

Next, let’s describe how you can create a transaction where more than one separate shipment occurred. In this case, each separate line can have its own addresses - or they can inherit their addresses from the document. You can mix and match these options on as many lines as necessary.

For the next example, let’s review how to sell two separate products when each must be shipped from a separate warehouse. One product will ship from a warehouse in Aberdeen, WA; the other will come from a Bainbridge Island warehouse.

  • First set the Bainbridge address at the document level. With this address at the document level, all lines will automatically inherit that address as its default.
  • Next set the addresses value for the custom line item. Because this value is set at the line level, it no longer inherits any addresses from the root document level, which means you must set both the ShipFrom and ShipTo values for that line.

Here’s what a line-level transaction looks like:

Test Case 3.2.2 - Line Level Addresses

Setup

  • Your DEVGUIDE company should have nexus in California and Washington.
  • In your connector, create the following transactions:
    • Document Type: SalesInvoice
    • Document Code: Chapter-3-Test-2
    • Company Code: DEVGUIDE
    • Document Date: 2017-06-15
    • Customer Code: TESTCUSTOMER
  • Addresses:
    • ShipFrom
      • 100 Ravine Lane NE, Bainbridge Island, WA 98110
    • ShipTo
      • 18300 Von Karman Ave, Irvine, CA 92612
  • Line #1:
    • Amount $65
    • TaxCode P0000000
    • ShipFrom
      • 422 S F St., Aberdeen, WA, US 98520
    • ShipTo
      • 18300 Von Karman Ave, Irvine, CA 92612
  • Line #2:
    • Amount $35
    • TaxCode P0000000
  • Calculate tax for your transaction using AvaTax.

Assertions

  • The taxable amount should be $100.00 with a total tax amount of $7.76.
  • Line1 should have a total tax amount of $5.04, while Line 2 has 2.72.
  • Both lines should be sourced in California with the following jurisdictions:
    • California State
    • Orange County
    • Orange County District Tax/Special Tax
    • Orange County Local Tax/Special Tax
  • {
      "type": "SalesInvoice",
      "code": "Chapter-3-Test-2",
      "companyCode": "DEVGUIDE",
      "date": "2017-06-15",
      "customerCode": "TESTCUSTOMER",
      "addresses": {
        "shipFrom": {
          "line1": "100 Ravine Lane NE",
          "city": "Bainbridge Island",
          "region": "WA",
          "country": "US",
          "postalCode": "98110"
        },
        "shipTo": {
          "line1": "18300 Von Karman Ave",
          "city": "Irvine",
          "region": "CA",
          "country": "US",
          "postalCode": "92612"
        }
      },
      "lines": [
        {
          "number": "1",
          "amount": 65,
          "taxCode": "P0000000",
          "addresses": {
            "shipFrom": {
              "line1": "422 S F St.",
              "city": "Aberdeen",
              "region": "WA",
              "country": "US",
              "postalCode": "98520"
            },
            "shipTo": {
              "line1": "21068 Bake Pkwy",
              "city": "Lake Forest",
              "region": "CA",
              "country": "US",
              "postalCode": "92630"
            }
          }
        },
        {
          "number": "2",
          "amount": 35,
          "taxCode": "P0000000"
        }
      ]
    }
                    

Address Types

Most developers instinctively understand the meaning of the address types ShipFrom and ShipTo, but often have questions about the “Point Of Order” address types. It’s worth taking a brief moment to explain address types in more detail.

Address Type Also Known As Usage
ShipFrom Origin The origination address where the products were shipped from, or from where the services originated.
ShipTo Destination The destination address where the products were shipped to, or where the services were delivered.
Point of Order Origin The place of business where you receive the customer's order. This address type is valid in the United States only and only applies to tangible personal property.
Point of Order Acceptance The place of business where you accept/approve the customer's order, thereby becoming contractually obligated to make the sale. This address type is valid in the United States only and only applies to tangible personal property.


In the United States, some jurisdictions have passed laws that require consideration of the point of order addresses. Please confer with your tax professional before using these address types.

If you are operating a retail point of presence, and you are physically selling goods and services in person, you can instead opt to use the SingleLocation address type. When you use SingleLocation, you are asserting that only one address was ever involved in the transaction.