Avalara Developer Network Developer avaTax

3.2 - Using Reference Fields

AvaTax provides a number of user reference fields for your convenience. For example, the referenceCode field is an optional field that can be used to tie your transaction back to your accounting system or to link to another transaction.

The referenceCode field exists at the document level, and other fields are available at the line level. Taken together, all of these reference fields can help you store extra information about the transaction in ways that are appropriate for your accounting system.

All of these fields are optional and are not required. Some connectors make use of all of these fields, others keep transactions extremely simple. It’s really up to you how much of this functionality you wish to implement.

Let’s look at each of these fields, and some ideas for how to make use of them. As a reminder, there is no data structure to this field, you can put anything you want!

Document Level Reference Fields

The following reference fields are available for your use at the document level. This means that they will only occur once in a transaction.

Field Name Ideas for Usage
ReferenceCode This field can link to the unique ID number of the invoice in your existing accounting system.
PurchaseOrderNo Intended to match to your customer's purchase order number, if one was provided.
SalespersonCode When tracking performance by salesperson, or identifying orders written by certain sales team members, this code can help you identify the author of the invoice.
Description A general purpose description of the invoice or transaction, or a comment explaining the transaction.
PosLaneCode If this transaction was made at a retail cash register, this code can be used to identify which cash register made the transaction.
Email The email address of the customer who requested the sale.

Line Level Reference Fields

Below is a list of the available reference fields available for customizing your transaction at the line level. Each line in your transaction can have its own values for each of these fields.

Field Name Ideas for Usage
Description Field provided to describe the item/service/shipping method for that given line. NOTE: If you participate in Streamlined Sales Tax, this field is required to be an accurate description of the product. Otherwise, it is optional and has no requirements.
RevenueAccount If your user wished to track this line item to a specific revenue account number in their accounting system, you could specify the revenue account number here.
Ref1 A user-supplied reference code for this line.
Ref2 A user-supplied reference code for this line.

Using Reference Fields

Let’s build out final test transaction using everything that we’ve covered in this chapter:

Test Case - 3.4.1

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-3
    • Document Date: 2017-06-15
    • Customer Code: TESTCUSTOMER
    • Reference Code: SalesOrder 123456
    • Sales Person Code: SA8675309
    • Purchase Order: PO6-5000
  • Addresses:
    • ShipFrom
      • 100 Ravine Lane NE, Bainbridge Island, WA, 98110
    • ShipTo
      • 18300 Von Karman Ave, Irvine, CA 92612
  • Line #1:
    • Amount $65
    • TaxCode P0000000
    • Description "A bundle of assorted yarn colors"
    • Ref1 "Item out of stock in Bainbridge Island distribution center. ShipFrom Aberdeen distribution center."
    • Ref2 "Customer would like the item to ShipTo a secondary address."
    • ShipFrom
      • 422 S F St., Aberdeen, WA, US 98520
    • ShipTo
      • 21068 Bake Pkwy, Lake Forest, CA 92630
  • Line #2:
    • Amount $35
    • TaxCode P0000000
    • Description "A single bolt of wool."
  • 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
  • Sourcing destination should be 21068 Bake Pkwy, Lake Forest, CA 92630.
  • Sourcing origin should be 422 S F St., Aberdeen, WA, US 98520.
  • Document level properties:
    • Reference Code field should list "SalesOrder 123456"
    • Sales Person should show as SA8675309
    • PO6-5000 should be listed as the Purchase Order
  • Line level properties:
    • Line 1:
      • The Description field should state "A bundle of assorted yarn colors"
    • Line 2:
      • The Description field should state "A single bolt of wool"
  • {
      "type": "SalesInvoice",
      "code": "Chapter-3-Test-3",
      "companyCode": "DEVGUIDE",
      "date": "2017-06-15",
      "customerCode": "TESTCUSTOMER",
      "referenceCode": "SalesOrder 123456",
      "salespersonCode": "SA8675309",
      "purchaseOrderNo": "PO2376500",
      "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": "92630"
        }
      },
      "lines": [
        {
          "number": "1",
          "amount": 65,
          "taxCode": "P0000000",
          "ref1": "Item out of stock in Bainbridge Island distribution center.  ShipFrom Aberdeen distribution center.",
          "ref2": "Customer would like the item to ShipTo a secondary address.",
          "description": "A bundle of assorted yarn colors",
          "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",
          "description": "A single bolt of wool."
        }
      ]
    }