TaxJar Sales Tax API for Go 
Official Go client for Sales Tax API v2. For the API documentation, please visit https://developers.taxjar.com/api/reference/.
Requirements
Installation
Authentication
Usage
Error Handling
Optional Configuration
Sandbox Environment
Testing
Requirements
- go1.11 or later.
Installation
go get -u github.com/taxjar/taxjar-go// Then, import the package:
import "github.com/taxjar/taxjar-go"Authentication
Generate a TaxJar API token. Enter the token when instantiating with NewClient. You may want to utilize an environment variable such as TAXJAR_API_KEY as seen below:
func NewClient(config ...Config) Config
// Instantiate client with your TaxJar API token:
client := taxjar.NewClient(taxjar.Config{
APIKey: os.Getenv("TAXJAR_API_KEY"),
})// or configure client after instantiating:
client := taxjar.NewClient()
client.APIKey = os.Getenv("TAXJAR_API_KEY")You're now ready to use TaxJar! Check out our quickstart guide to get up and running quickly.
Usage
Categories - List all tax categories
TaxForOrder - Calculate sales tax for an order
ListOrders - List order transactions
ShowOrder - Show order transaction
CreateOrder - Create order transaction
UpdateOrder - Update order transaction
DeleteOrder - Delete order transaction
ListRefunds - List refund transactions
ShowRefund - Show refund transaction
CreateRefund - Create refund transaction
UpdateRefund - Update refund transaction
DeleteRefund - Delete refund transaction
ListCustomers - List customers
ShowCustomer - Show customer
CreateCustomer - Create customer
UpdateCustomer - Update customer
DeleteCustomer - Delete customer
RatesForLocation - List tax rates for a location (by zip/postal code)
NexusRegions - List nexus regions
ValidateAddress - Validate an address
Validate - Validate a VAT number
SummaryRates - Summarize tax rates for all regions
List all tax categories (API docs)
The TaxJar API provides product-level tax rules for a subset of product categories. These categories are to be used for products that are either exempt from sales tax in some jurisdictions or are taxed at reduced rates. You need not pass in a product tax code for sales tax calculations on product that is fully taxable. Simply leave that parameter out.
func (client *Config) Categories() (*CategoriesResponse, error)
res, _ := client.Categories()
fmt.Println(res.Categories) // CategoriesResponse.CategoriesCalculate sales tax for an order (API docs)
Shows the sales tax that should be collected for a given order.
func (client *Config) TaxForOrder(params TaxForOrderParams) (*TaxForOrderResponse, error)
res, _ := client.TaxForOrder(taxjar.TaxForOrderParams{
FromCountry: "US",
FromZip: "94025",
FromState: "CA",
FromCity: "Menlo Park",
FromStreet: "2825 Sand Hill Rd",
ToCountry: "US",
ToZip: "94303",
ToState: "CA",
ToCity: "Palo Alto",
ToStreet: "5230 Newell Road",
Amount: 267.9,
Shipping: 0,
LineItems: []taxjar.TaxLineItem{
{
ID: "1",
Quantity: 1,
ProductTaxCode: "19005",
UnitPrice: 535.8,
Discount: 267.9,
},
},
})
fmt.Println(res.Tax) // TaxForOrderResponse.Tax
fmt.Println(res.Tax.AmountToCollect) // TaxForOrderResponse.Tax.AmountToCollectList order transactions (API docs)
Lists existing order transactions created through the API.
func (client *Config) ListOrders(params ListOrdersParams) (*ListOrdersResponse, error)
res, _ := client.ListOrders(ListOrdersParams{
FromTransactionDate: "2015/05/01",
ToTransactionDate: "2015/05/31",
})
fmt.Println(res.Orders) // ListOrdersResponse.OrdersShow order transaction (API docs)
Shows an existing order transaction created through the API.
func (client *Config) ShowOrder(transactionID string, params ...ShowOrderParams) (*ShowOrderResponse, error)
res, _ := client.ShowOrder("123")
fmt.Println(res.Order) // ShowOrderResponse.OrderCreate order transaction (API docs)
Creates a new order transaction.
func (client *Config) CreateOrder(params CreateOrderParams) (*CreateOrderResponse, error)
res, _ := client.CreateOrder(taxjar.CreateOrderParams{
TransactionID: "123",
TransactionDate: "2019/05/15",
FromCountry: "US",
FromZip: "94025",
FromState: "CA",
FromCity: "Menlo Park",
FromStreet: "2825 Sand Hill Rd",
ToCountry: "US",
ToZip: "94303",
ToState: "CA",
ToCity: "Palo Alto",
ToStreet: "5230 Newell Road",
Amount: 267.9,
Shipping: 0,
SalesTax: 0,
LineItems: []taxjar.OrderLineItem{
{
ID: "1",
Quantity: 1,
Description: "Legal Services",
ProductTaxCode: "19005",
UnitPrice: 535.8,
Discount: 267.9,
SalesTax: 0,
},
},
})
fmt.Println(res.Order) // CreateOrderResponse.OrderUpdate order transaction (API docs)
Updates an existing order transaction created through the API.
func (client *Config) UpdateOrder(params UpdateOrderParams) (*UpdateOrderResponse, error)
res, _ := client.UpdateOrder(taxjar.UpdateOrderParams{
TransactionID: "123",
Amount: 283.6,
Shipping: 5,
SalesTax: 1.04,
LineItems: []taxjar.OrderLineItem{
{
ID: "1",
Quantity: 1,
Description: "Legal Services",
ProductTaxCode: "19005",
UnitPrice: 535.8,
Discount: 267.9,
SalesTax: 0,
},
{
ID: "2",
Quantity: 2,
Description: "Hoberman Switch Pitch",
UnitPrice: 10.7,
Discount: 10.7,
SalesTax: 1.04,
},
},
})
fmt.Println(res.Order) // UpdateOrderResponse.OrderDelete order transaction (API docs)
Deletes an existing order transaction created through the API.
func (client *Config) DeleteOrder(transactionID string, params ...DeleteOrderParams) (*DeleteOrderResponse, error)
res, _ := client.DeleteOrder("123")
fmt.Println(res.Order) // DeleteOrderResponse.OrderList refund transactions (API docs)
Lists existing refund transactions created through the API.
func (client *Config) ListRefunds(params ListRefundsParams) (*ListRefundsResponse, error)
res, _ := client.ListRefunds(taxjar.ListRefundsParams{
FromTransactionDate: "2015/05/01",
ToTransactionDate: "2015/05/31",
})
fmt.Println(res.Refunds) // ListRefundsResponse.RefundsShow refund transaction (API docs)
Shows an existing refund transaction created through the API.
func (client *Config) ShowRefund(transactionID string, params ...ShowRefundParams) (*ShowRefundResponse, error)
res, _ := client.ShowRefund("321")
fmt.Println(res.Refund) // ShowRefundResponse.RefundCreate refund transaction (API docs)
Creates a new refund transaction.
func (client *Config) CreateRefund(params CreateRefundParams) (*CreateRefundResponse, error)
res, _ := client.CreateRefund(taxjar.CreateRefundParams{
TransactionID: "123-refund",
TransactionReferenceID: "123",
TransactionDate: "2019/05/15",
FromCountry: "US",
FromZip: "94025",
FromState: "CA",
FromCity: "Menlo Park",
FromStreet: "2825 Sand Hill Rd",
ToCountry: "US",
ToZip: "94303",
ToState: "CA",
ToCity: "Palo Alto",
ToStreet: "5230 Newell Road",
Amount: -5.35,
Shipping: -0,
SalesTax: -0.52,
LineItems: []taxjar.RefundLineItem{
{
ID: "1",
Quantity: 1,
Description: "Legal Services",
ProductTaxCode: "19005",
UnitPrice: -0,
Discount: -0,
SalesTax: -0,
},
{
ID: "2",
Quantity: 1,
Description: "Hoberman Switch Pitch",
UnitPrice: -0,
Discount: -5.35,
SalesTax: -0.52,
},
},
})
fmt.Println(res.Refund) // CreateRefundResponse.RefundUpdate refund transaction (API docs)
Updates an existing refund transaction created through the API.
func (client *Config) UpdateRefund(params UpdateRefundParams) (*UpdateRefundResponse, error)
res, _ := client.UpdateRefund(taxjar.UpdateRefundParams{
TransactionID: "123-refund",
TransactionReferenceID: "123",
Amount: -10.35,
Shipping: -5,
})
fmt.Println(res.Refund) // UpdateRefundResponse.RefundDelete refund transaction (API docs)
Deletes an existing refund transaction created through the API.
func (client *Config) DeleteRefund(transactionID string, params ...DeleteRefundParams) (*DeleteRefundResponse, error)
res, _ := client.DeleteRefund("123-refund")
fmt.Println(res.Refund) // DeleteRefundResponse.RefundList customers (API docs)
Lists existing customers created through the API.
func (client *Config) ListCustomers() (*ListCustomersResponse, error)
res, _ := client.ListCustomers()
fmt.Println(res.Customers) // ListCustomersResponse.CustomersShow customer (API docs)
Shows an existing customer created through the API.
func (client *Config) ShowCustomer(customerID string) (*ShowCustomerResponse, error)
res, _ := client.ShowCustomer("123")
fmt.Println(res.Customer) // ShowCustomerResponse.CustomerCreate customer (API docs)
Creates a new customer.
func (client *Config) CreateCustomer(params CreateCustomerParams) (*CreateCustomerResponse, error)
res, _ := client.CreateCustomer(taxjar.CreateCustomerParams{
CustomerID: "123",
ExemptionType: "wholesale",
Name: "Initech",
ExemptRegions: []taxjar.ExemptRegion{
{
Country: "US",
State: "TX",
},
},
Country: "US",
State: "TX",
Zip: "78744",
City: "Austin",
Street: "4120 Freidrich Lane",
})
fmt.Println(res.Customer) // CreateCustomerResponse.CustomerUpdate customer (API docs)
Updates an existing customer created through the API.
func (client *Config) UpdateCustomer(params UpdateCustomerParams) (*UpdateCustomerResponse, error)
res, _ := client.UpdateCustomer(taxjar.UpdateCustomerParams{
CustomerID: "123",
ExemptionType: "non_exempt",
Name: "Initech",
ExemptRegions: []taxjar.ExemptRegion{
{
Country: "US",
State: "MA",
},
{
Country: "US",
State: "TX",
},
},
})
fmt.Println(res.Customer) // UpdateCustomerResponse.CustomerDelete customer (API docs)
Deletes an existing customer created through the API.
func (client *Config) DeleteCustomer(customerID string) (*DeleteCustomerResponse, error)
res, _ := client.DeleteCustomer("123")
fmt.Println(res.Customer) // DeleteCustomerResponse.CustomerList tax rates for a location (by zip/postal code) (API docs)
Shows the sales tax rates for a given location.
Please note this method only returns the full combined rate for a given location. It does not support nexus determination, sourcing based on a ship from and ship to address, shipping taxability, product exemptions, customer exemptions, or sales tax holidays. We recommend using
TaxForOrderto accurately calculate sales tax for an order.
func (client *Config) RatesForLocation(zip string, params ...RatesForLocationParams) (*RatesForLocationResponse, error)
res, _ := client.RatesForLocation("90002")
fmt.Println(res.Rate) // RatesForLocationResponse.RateList nexus regions (API docs)
Lists existing nexus locations for a TaxJar account.
func (client *Config) NexusRegions() (*NexusRegionsResponse, error)
res, _ := client.NexusRegions()
fmt.Println(res.Regions) // NexusRegionsResponse.RegionsValidate an address (API docs)
Validates a customer address and returns back a collection of address matches. Address validation requires a TaxJar Plus subscription.
func (client *Config) ValidateAddress(params ValidateAddressParams) (*ValidateAddressResponse, error)
res, _ := client.ValidateAddress(taxjar.ValidateAddressParams{
Country: "US",
State: "AZ",
Zip: "85297",
City: "Gilbert",
Street: "3301 South Greenfield Rd",
})
fmt.Println(res.Addresses) // ValidateAddressResponse.AddressesValidate a VAT number (API docs)
Validates an existing VAT identification number against VIES.
func (client *Config) Validate(params ValidateParams) (*ValidateResponse, error)
res, _ := client.Validate({
VAT: "FR40303265045",
})
fmt.Println(res.Validation) // ValidateResponse.ValidationSummarize tax rates for all regions (API docs)
Retrieve minimum and average sales tax rates by region as a backup.
This method is useful for periodically pulling down rates to use if the TaxJar API is unavailable. However, it does not support nexus determination, sourcing based on a ship from and ship to address, shipping taxability, product exemptions, customer exemptions, or sales tax holidays. We recommend using
TaxForOrderto accurately calculate sales tax for an order.
func (client *Config) SummaryRates() (*SummaryRatesResponse, error)
res, _ := client.SummaryRates()
fmt.Println(res.SummaryRates) // SummaryRatesResponse.SummaryRatesError Handling
res, err := client.TaxForOrder(taxjar.TaxForOrderParams{
FromCountry: "US",
FromZip: "94025",
FromState: "CA",
FromCity: "Menlo Park",
FromStreet: "2825 Sand Hill Rd",
ToCountry: "US",
ToZip: "94303",
ToState: "CA",
ToCity: "Palo Alto",
ToStreet: "5230 Newell Road",
Amount: 267.9,
Shipping: 0,
LineItems: []taxjar.TaxLineItem{
{
ID: "1",
Quantity: 1,
ProductTaxCode: "19005",
UnitPrice: 535.8,
Discount: 267.9,
},
},
})
if err != nil {
fmt.Println(err) // taxjar: 401 Unauthorized - Not Authorized for route 'POST /v2/taxes'
} else {
fmt.Println(res.Tax)
}
// or extract more information by asserting to `*taxjar.Error`
if err := err.(*taxjar.Error); err != nil {
fmt.Println(err.Status) // 401
fmt.Println(err.Err) // Unauthorized
fmt.Println(err.Detail) // Not authorized for route `POST /v2/taxes'
fmt.Printf("%+v", errors.Wrap(err, "")) // Stack trace:
// taxjar: 401 Unauthorized - Not Authorized for route 'POST /v2/taxes'
//
// main.main
// /Path/to/your/file.go:292
// runtime.main
// /usr/local/go/src/runtime/proc.go:200
// runtime.goexit
// /usr/local/go/src/runtime/asm_amd64.s:1337
} else {
fmt.Println(res.Tax)
}Optional Configuration
To add additional headers to each request, assign them to client.Headers. For example, to test specific error response codes, pass the custom X-TJ-Expected-Response header:
client.Headers = map[string]interface{}{
"X-TJ-Expected-Response": 422,
}If you'd like to customize the timeout for requests, pass a time value to client.Timeout.
client.Timeout = 45 * time.Second // taxjar.DefaultTimeout: 30 * time.SecondTo set more detailed timeouts, you may also pass a custom transport to client.Transport.
client.Transport = &http.Transport{
DialContext: (&net.Dialer{
Timeout: 20 * Time.Second,
KeepAlive: 20 * Time.Second,
}).DialContext,
TLSHandshakeTimeout: 20 * time.Second,
ExpectContinueTimeout: 8 * time.Second,
ResponseHeaderTimeout: 6 * time.Second,
}
/* taxjar.DefaultTransport:
&http.Transport{
DialContext: (&net.Dialer{
Timeout: 10 * Time.Second,
KeepAlive: 10 * Time.Second,
}).DialContext,
TLSHandshakeTimeout: 10 * time.Second,
ExpectContinueTimeout: 4 * time.Second,
ResponseHeaderTimeout: 3 * time.Second,
}
*/For even more customization, pass a custom *http.Client to client.HTTPClient.
client.HTTPClient = &http.Client{/* your configuration here */}Sandbox Environment
You may also configure the client to use TaxJar's sandbox environment. The sandbox environment requires a TaxJar Plus subscription.
import "github.com/taxjar/taxjar-go"
// Instantiate client and set `APIURL`:
client := taxjar.NewClient(taxjar.Config{
APIKey: os.Getenv("TAXJAR_SANDBOX_API_KEY"),
APIURL: taxjar.SandboxAPIURL,
})
// or
client := taxjar.NewClient()
client.APIKey = os.Getenv("TAXJAR_SANDBOX_API_KEY")
client.APIURL = taxjar.SandboxAPIURLTesting
make testTo validate API methods in the TaxJar sandbox environment, pass the following environment variables:
TAXJAR_API_URL="https://api.sandbox.taxjar.com" \
TAXJAR_API_KEY="9e0cd62a22f451701f29c3bde214" \
make test