ScottRudiger/taxjar-java

Sales Tax API Client for Java

TaxJar Sales Tax API for Java

Official Java client for SmartCalcs by TaxJar. For the API documentation, please visit http://developers.taxjar.com/api.

Getting Started

We recommend installing taxjar-java with Maven or Gradle. Before authenticating, get your API key from TaxJar.

Maven

Add the following dependency to your project's pom.xml file:

<dependency>
    <groupId>com.taxjar</groupId>
    <artifactId>taxjar-java</artifactId>
    <version>3.0.0</version>
</dependency>

Gradle

Add the following dependency to your project's build file:

compile "com.taxjar:taxjar-java:3.0.0"

Manual Installation

You can manually install the following JARs (including dependencies) here:

• TaxJar JAR
• Retrofit
• Retrofit Gson Converter

Package Dependencies

taxjar-java is built for Java 1.7+ and requires the following dependencies:

• Retrofit - Includes OkHttp and Gson
• Retrofit Converter Gson

Authentication

To authenticate with our API, simply instantiate the client with your TaxJar API token:

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;

public class AuthenticationExample {

    public static void main(String[] args) {
        Taxjar client = new Taxjar("YOUR API TOKEN");
    }

}

Usage

All methods in the Taxjar class support synchronous and asynchronous requests. For async examples, see the project's functional tests.

List all tax categories

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;
import com.taxjar.model.categories.CategoryResponse;

public class CategoryExample {

    public static void main(String[] args) {
        Taxjar client = new Taxjar("YOUR API TOKEN");
        
        try {
            CategoryResponse res = client.categories();
        } catch (TaxjarException e) {
            e.printStackTrace();
        }
    }

}

List tax rates for a location (by zip/postal code)

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;
import com.taxjar.model.rates.RateResponse;
import java.util.HashMap;
import java.util.Map;

public class RatesExample {

    public static void main(String[] args) {
        Taxjar client = new Taxjar("YOUR API TOKEN");
        
        try {
            Map<String, String> params = new HashMap<>();
            params.put("country", "US");
            params.put("city", "Watts");
            params.put("street", "123 Test St");
            RateResponse res = client.ratesForLocation("90002", params);
        } catch (TaxjarException e) {
            e.printStackTrace();
        }
    }

}

Calculate sales tax for an order

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;
import com.taxjar.model.taxes.TaxResponse;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class TaxExample {

    public static void main(String[] args) {
        Taxjar client = new Taxjar("YOUR API TOKEN");
        
        try {
            Map<String, Object> params = new HashMap<>();
            params.put("from_country", "US");
            params.put("from_zip", "92093");
            params.put("from_state", "CA");
            params.put("from_city", "La Jolla");
            params.put("from_street", "9500 Gilman Drive");
            params.put("to_country", "US");
            params.put("to_zip", "90002");
            params.put("to_state", "CA");
            params.put("to_city", "Los Angeles");
            params.put("to_street", "1335 E 103rd St");
            params.put("amount", 15);
            params.put("shipping", 1.5);

            List<Map> nexusAddresses = new ArrayList();
            Map<String, Object> nexusAddress = new HashMap<>();
            nexusAddress.put("country", "US");
            nexusAddress.put("zip", "92093");
            nexusAddress.put("state", "CA");
            nexusAddress.put("city", "La Jolla");
            nexusAddress.put("street", "9500 Gilman Drive");
            nexusAddresses.add(nexusAddress);

            List<Map> lineItems = new ArrayList();
            Map<String, Object> lineItem = new HashMap<>();
            lineItem.put("id", 1);
            lineItem.put("quantity", 1);
            lineItem.put("product_tax_code", "20010");
            lineItem.put("unit_price", 15);
            lineItem.put("discount", 0);
            lineItems.add(lineItem);

            params.put("nexus_addresses", nexusAddresses);
            params.put("line_items", lineItems);

            TaxResponse res = client.taxForOrder(params);
        } catch (TaxjarException e) {
            e.printStackTrace();
        }
    }

}

List order transactions

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;
import com.taxjar.model.transactions.OrdersResponse;
import java.util.HashMap;
import java.util.Map;

public class ListOrdersExample {

    public static void main(String[] args) {
        Taxjar client = new Taxjar("YOUR API TOKEN");
        
        try {
            Map<String, String> params = new HashMap<>();
            params.put("from_transaction_date", "2015/05/01");
            params.put("to_transaction_date", "2015/05/31");
            OrdersResponse res = client.listOrders(params);
        } catch (TaxjarException e) {
            e.printStackTrace();
        }
    }

}

Show order transaction

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;
import com.taxjar.model.transactions.OrderResponse;

public class ShowOrderExample {

    public static void main(String[] args) {
        Taxjar client = new Taxjar("YOUR API TOKEN");
        
        try {
            OrderResponse res = client.showOrder("123");
        } catch (TaxjarException e) {
            e.printStackTrace();
        }
    }

}

Create order transaction

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;
import com.taxjar.model.transactions.OrderResponse;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class CreateOrderExample {

    public static void main(String[] args) {
        Taxjar client = new Taxjar("YOUR API TOKEN");
        
        try {
            Map<String, Object> params = new HashMap<>();
            params.put("transaction_id", "123");
            params.put("transaction_date", "2015/05/04");
            params.put("to_country", "US");
            params.put("to_zip", "90002");
            params.put("to_city", "Los Angeles");
            params.put("to_street", "123 Palm Grove Ln");
            params.put("amount", 16.5);
            params.put("shipping", 1.5);
            params.put("sales_tax", 0.95);

            List<Map> lineItems = new ArrayList();
            Map<String, Object> lineItem = new HashMap<>();
            lineItem.put("quantity", 1);
            lineItem.put("product_identifier", "12-34243-0");
            lineItem.put("description", "Heavy Widget");
            lineItem.put("unit_price", 15);
            lineItem.put("sales_tax", 0.95);
            lineItems.add(lineItem);

            params.put("line_items", lineItems);

            OrderResponse res = client.createOrder(params);
        } catch (TaxjarException e) {
            e.printStackTrace();
        }
    }

}

Update order transaction

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;
import com.taxjar.model.transactions.OrderResponse;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class UpdateOrderExample {

    public static void main(String[] args) {
        Taxjar client = new Taxjar("YOUR API TOKEN");
        
        try {
            Map<String, Object> params = new HashMap<>();
            params.put("transaction_id", "123");
            params.put("transaction_date", "2015/05/04");
            params.put("to_country", "US");
            params.put("to_zip", "90002");
            params.put("to_city", "Los Angeles");
            params.put("to_street", "123 Palm Grove Ln");
            params.put("amount", 17);
            params.put("shipping", 2);
            params.put("sales_tax", 0.95);

            List<Map> lineItems = new ArrayList();
            Map<String, Object> lineItem = new HashMap<>();
            lineItem.put("quantity", 1);
            lineItem.put("product_identifier", "12-34243-0");
            lineItem.put("description", "Heavy Widget");
            lineItem.put("unit_price", 15);
            lineItem.put("sales_tax", 0.95);
            lineItems.add(lineItem);

            params.put("line_items", lineItems);

            OrderResponse res = client.updateOrder("123", params);
        } catch (TaxjarException e) {
            e.printStackTrace();
        }
    }

}

Delete order transaction

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;
import com.taxjar.model.transactions.OrderResponse;

public class DeleteOrderExample {

    public static void main(String[] args) {
        Taxjar client = new Taxjar("YOUR API TOKEN");
        
        try {
            OrderResponse res = client.deleteOrder("123");
        } catch (TaxjarException e) {
            e.printStackTrace();
        }
    }

}

List refund transactions

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;
import com.taxjar.model.transactions.RefundsResponse;
import java.util.HashMap;
import java.util.Map;

public class ListRefundsExample {

    public static void main(String[] args) {
        Taxjar client = new Taxjar("YOUR API TOKEN");
        
        try {
            Map<String, String> params = new HashMap<>();
            params.put("from_transaction_date", "2015/05/01");
            params.put("to_transaction_date", "2015/05/31");
            RefundsResponse res = client.listRefunds(params);
        } catch (TaxjarException e) {
            e.printStackTrace();
        }
    }

}

Show refund transaction

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;
import com.taxjar.model.transactions.RefundResponse;

public class ShowRefundExample {

    public static void main(String[] args) {
        Taxjar client = new Taxjar("YOUR API TOKEN");
        
        try {
            RefundResponse res = client.showRefund("321");
        } catch (TaxjarException e) {
            e.printStackTrace();
        }
    }

}

Create refund transaction

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;
import com.taxjar.model.transactions.RefundResponse;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class CreateRefundExample {

    public static void main(String[] args) {
        Taxjar client = new Taxjar("YOUR API TOKEN");
        
        try {
            Map<String, Object> params = new HashMap<>();
            params.put("transaction_id", "321");
            params.put("transaction_date", "2015/05/04");
            params.put("to_country", "US");
            params.put("to_zip", "90002");
            params.put("to_city", "Los Angeles");
            params.put("to_street", "123 Palm Grove Ln");
            params.put("amount", 16.5);
            params.put("shipping", 1.5);
            params.put("sales_tax", 0.95);

            List<Map> lineItems = new ArrayList();
            Map<String, Object> lineItem = new HashMap<>();
            lineItem.put("quantity", 1);
            lineItem.put("product_identifier", "12-34243-0");
            lineItem.put("description", "Heavy Widget");
            lineItem.put("unit_price", 15);
            lineItem.put("sales_tax", 0.95);
            lineItems.add(lineItem);

            params.put("line_items", lineItems);

            RefundResponse res = client.createRefund(params);
        } catch (TaxjarException e) {
            e.printStackTrace();
        }
    }

}

Update refund transaction

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;
import com.taxjar.model.transactions.RefundResponse;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class UpdateRefundExample {

    public static void main(String[] args) {
        Taxjar client = new Taxjar("YOUR API TOKEN");
        
        try {
            Map<String, Object> params = new HashMap<>();
            params.put("transaction_id", "321");
            params.put("transaction_date", "2015/05/04");
            params.put("to_country", "US");
            params.put("to_zip", "90002");
            params.put("to_city", "Los Angeles");
            params.put("to_street", "123 Palm Grove Ln");
            params.put("amount", 17);
            params.put("shipping", 2);
            params.put("sales_tax", 0.95);

            List<Map> lineItems = new ArrayList();
            Map<String, Object> lineItem = new HashMap<>();
            lineItem.put("quantity", 1);
            lineItem.put("product_identifier", "12-34243-0");
            lineItem.put("description", "Heavy Widget");
            lineItem.put("unit_price", 15);
            lineItem.put("sales_tax", 0.95);
            lineItems.add(lineItem);

            params.put("line_items", lineItems);

            RefundResponse res = client.updateRefund("321", params);
        } catch (TaxjarException e) {
            e.printStackTrace();
        }
    }

}

Delete refund transaction

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;
import com.taxjar.model.transactions.RefundResponse;

public class DeleteOrderExample {

    public static void main(String[] args) {
        Taxjar client = new Taxjar("YOUR API TOKEN");
        
        try {
            OrderResponse res = client.deleteRefund("321");
        } catch (TaxjarException e) {
            e.printStackTrace();
        }
    }

}

List customers

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;
import com.taxjar.model.customers.CustomersResponse;
import java.util.HashMap;
import java.util.Map;

public class ListCustomersExample {

    public static void main(String[] args) {
        Taxjar client = new Taxjar("YOUR API TOKEN");
        
        try {
            CustomersResponse res = client.listCustomers();
        } catch (TaxjarException e) {
            e.printStackTrace();
        }
    }

}

Show customer

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;
import com.taxjar.model.customers.CustomerResponse;

public class ShowCustomerExample {

    public static void main(String[] args) {
        Taxjar client = new Taxjar("YOUR API TOKEN");
        
        try {
            CustomerResponse res = client.showCustomer("123");
        } catch (TaxjarException e) {
            e.printStackTrace();
        }
    }

}

Create customer

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;
import com.taxjar.model.customers.CustomerResponse;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class CreateCustomerExample {

    public static void main(String[] args) {
        Taxjar client = new Taxjar("YOUR API TOKEN");
        
        try {
            Map<String, Object> params = new HashMap<>();
            params.put("customer_id", "123");
            params.put("exemption_type", "wholesale");
            params.put("name", "Dunder Mifflin Paper Company");
            params.put("country", "US");
            params.put("state", "PA");
            params.put("zip", "18504");
            params.put("city", "Scranton");
            params.put("street", "1725 Slough Avenue");

            List<Map> exemptRegions = new ArrayList();

            Map<String, String> exemptRegion = new HashMap<>();
            exemptRegion.put("country", "US");
            exemptRegion.put("state", "FL");

            Map<String, String> exemptRegion2 = new HashMap<>();
            exemptRegion.put("country", "US");
            exemptRegion.put("state", "PA");

            exemptRegions.add(exemptRegion);
            exemptRegions.add(exemptRegion2);

            params.put("exempt_regions", exemptRegions);

            CustomerResponse res = client.createCustomer(params);
        } catch (TaxjarException e) {
            e.printStackTrace();
        }
    }

}

Update customer

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;
import com.taxjar.model.customers.CustomerResponse;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class UpdateCustomerExample {

    public static void main(String[] args) {
        Taxjar client = new Taxjar("YOUR API TOKEN");
        
        try {
            Map<String, Object> params = new HashMap<>();
            params.put("customer_id", "123");
            params.put("exemption_type", "wholesale");
            params.put("name", "Sterling Cooper");
            params.put("country", "US");
            params.put("state", "NY");
            params.put("zip", "10010");
            params.put("city", "New York");
            params.put("street", "405 Madison Ave");

            List<Map> exemptRegions = new ArrayList();

            Map<String, String> exemptRegion = new HashMap<>();
            exemptRegion.put("country", "US");
            exemptRegion.put("state", "NY");

            exemptRegions.add(exemptRegion);

            params.put("exempt_regions", exemptRegions);

            CustomerResponse res = client.updateCustomer("123", params);
        } catch (TaxjarException e) {
            e.printStackTrace();
        }
    }

}

Delete customer

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;
import com.taxjar.model.customers.CustomerResponse;

public class DeleteCustomerExample {

    public static void main(String[] args) {
        Taxjar client = new Taxjar("YOUR API TOKEN");
        
        try {
            CustomerResponse res = client.deleteCustomer("123");
        } catch (TaxjarException e) {
            e.printStackTrace();
        }
    }

}

List nexus regions

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;
import com.taxjar.model.nexus.RegionResponse;

public class NexusRegionsExample {

    public static void main(String[] args) {
        Taxjar client = new Taxjar("YOUR API TOKEN");
        
        try {
            RegionResponse res = client.nexusRegions();
        } catch (TaxjarException e) {
            e.printStackTrace();
        }
    }

}

Validate a VAT number

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;
import com.taxjar.model.validations.ValidationResponse;
import java.util.HashMap;
import java.util.Map;

public class ValidateExample {

    public static void main(String[] args) {
        Taxjar client = new Taxjar("YOUR API TOKEN");
        
        try {
            Map<String, String> params = new HashMap<>();
            params.put("vat", "FR40303265045");

            ValidationResponse res = client.validateVat(params);
        } catch (TaxjarException e) {
            e.printStackTrace();
        }
    }

}

Summarize tax rates for all regions

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;
import com.taxjar.model.summarized_rates.SummaryRateResponse;

public class SummarizedRatesExample {

    public static void main(String[] args) {
        Taxjar client = new Taxjar("YOUR API TOKEN");
        
        try {
            SummaryRateResponse res = client.summaryRates();
        } catch (TaxjarException e) {
            e.printStackTrace();
        }
    }

}

Custom Options

You can pass additional options using setApiConfig or when instantiating the client for the following:

Timeouts

The default timeout is 30 seconds (specified in milliseconds).

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;
import java.util.HashMap;
import java.util.Map;

public class CustomTimeoutExample {

    public static void main(String[] args) {
        // Custom timeout when instantiating the client
        Map<String, Object> params = new HashMap<>();
        params.put("timeout", 30 * 1000);

        Taxjar client = new Taxjar("YOUR API TOKEN", params);

        // Custom timeout via `setApiConfig`
        client.setApiConfig("timeout", 30 * 1000);
    }

}

Sandbox Environment

You can easily configure the client to use the TaxJar Sandbox:

import com.taxjar.Taxjar;
import com.taxjar.exception.TaxjarException;
import java.util.HashMap;
import java.util.Map;

public class SandboxExample {

    public static void main(String[] args) {
        Map<String, Object> params = new HashMap<>();
        params.put("apiUrl", Taxjar.SANDBOX_API_URL);

        Taxjar client = new Taxjar("YOUR SANDBOX API TOKEN", params);
    }

}

Tests

We use JUnit v3.8.1 with a custom interceptor for Retrofit to directly test client methods.

More Information

More information can be found at TaxJar Developers.

License

taxjar-java is released under the MIT License.

Support

Bug reports and feature requests should be filed on the GitHub issue tracking page.

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new pull request