Avalara provides automated tax calculation, compliance, and reporting solutions. This guide covers complete integration with Avalara's AvaTax API in Java/Spring Boot.
1. Project Setup and Dependencies
Maven Dependencies (pom.xml)
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>avalara-tax-integration</artifactId>
<version>1.0.0</version>
<properties>
<maven.compiler.source>11</maven.compiler.source>
<maven.compiler.target>11</maven.compiler.target>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<spring.boot.version>2.7.14</spring.boot.version>
<jackson.version>2.15.2</jackson.version>
<okhttp.version>4.11.0</okhttp.version>
</properties>
<dependencies>
<!-- Spring Boot -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<version>${spring.boot.version}</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
<version>${spring.boot.version}</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
<version>${spring.boot.version}</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-cache</artifactId>
<version>${spring.boot.version}</version>
</dependency>
<!-- HTTP Client -->
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>okhttp</artifactId>
<version>${okhttp.version}</version>
</dependency>
<!-- JSON Processing -->
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>${jackson.version}</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.datatype</groupId>
<artifactId>jackson-datatype-jsr310</artifactId>
<version>${jackson.version}</version>
</dependency>
<!-- Database -->
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<scope>runtime</scope>
</dependency>
<!-- Lombok -->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<optional>true</optional>
</dependency>
<!-- Cache -->
<dependency>
<groupId>com.github.ben-manes.caffeine</groupId>
<artifactId>caffeine</artifactId>
<version>3.1.6</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>${spring.boot.version}</version>
</plugin>
</plugins>
</build>
</project>
2. Configuration Classes
Application Properties (application.yml)
# Avalara Configuration
avalara:
base-url: ${AVALARA_BASE_URL:https://sandbox-rest.avatax.com}
account-id: ${AVALARA_ACCOUNT_ID:}
license-key: ${AVALARA_LICENSE_KEY:}
company-code: ${AVALARA_COMPANY_CODE:DEFAULT}
timeout: 30000
max-retries: 3
machine-name: ${HOSTNAME:tax-service}
app-name: TaxService
app-version: 1.0
environment: ${AVALARA_ENVIRONMENT:sandbox}
# Cache Configuration
cache:
tax-rates:
ttl: 3600 # 1 hour
# Server Configuration
server:
port: 8080
# Database
spring:
datasource:
url: jdbc:h2:mem:testdb
driverClassName: org.h2.Driver
username: sa
password:
jpa:
database-platform: org.hibernate.dialect.H2Dialect
hibernate:
ddl-auto: create-drop
show-sql: true
h2:
console:
enabled: true
path: /h2-console
# Logging
logging:
level:
com.example.avalara: DEBUG
Avalara Configuration Class
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
@Data
@Component
@ConfigurationProperties(prefix = "avalara")
public class AvalaraConfig {
private String baseUrl;
private String accountId;
private String licenseKey;
private String companyCode = "DEFAULT";
private int timeout = 30000;
private int maxRetries = 3;
private String machineName = "tax-service";
private String appName = "TaxService";
private String appVersion = "1.0";
private String environment = "sandbox";
}
3. Database Entities
Tax Transaction Entity
import lombok.Data;
import javax.persistence.*;
import java.math.BigDecimal;
import java.time.LocalDateTime;
import java.util.Map;
@Entity
@Table(name = "tax_transactions")
@Data
public class TaxTransaction {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(name = "transaction_code", unique = true)
private String transactionCode;
@Column(name = "avalara_transaction_id")
private String avalaraTransactionId;
@Column(name = "document_type")
@Enumerated(EnumType.STRING)
private DocumentType documentType;
@Column(name = "transaction_date")
private LocalDateTime transactionDate;
@Column(name = "customer_code")
private String customerCode;
@Column(name = "company_code")
private String companyCode;
@Column(name = "total_amount", precision = 15, scale = 4)
private BigDecimal totalAmount;
@Column(name = "total_tax", precision = 15, scale = 4)
private BigDecimal totalTax;
@Column(name = "taxable_amount", precision = 15, scale = 4)
private BigDecimal taxableAmount;
@Column(name = "exempt_amount", precision = 15, scale = 4)
private BigDecimal exemptAmount;
@Column(name = "currency_code")
private String currencyCode = "USD";
@Column(name = "origin_address_id")
private Long originAddressId;
@Column(name = "destination_address_id")
private Long destinationAddressId;
@Column(name = "status")
@Enumerated(EnumType.STRING)
private TransactionStatus status;
@Column(name = "commit_status")
private Boolean commitStatus = false;
@Column(name = "tax_calculation_date")
private LocalDateTime taxCalculationDate;
@Column(name = "created_at")
private LocalDateTime createdAt;
@Column(name = "updated_at")
private LocalDateTime updatedAt;
@PrePersist
protected void onCreate() {
createdAt = LocalDateTime.now();
updatedAt = LocalDateTime.now();
if (transactionDate == null) {
transactionDate = LocalDateTime.now();
}
}
@PreUpdate
protected void onUpdate() {
updatedAt = LocalDateTime.now();
}
public enum DocumentType {
SalesOrder, SalesInvoice, PurchaseOrder, PurchaseInvoice, ReturnOrder, ReturnInvoice
}
public enum TransactionStatus {
TEMPORARY, SAVED, POSTED, COMMITTED, CANCELLED, ADJUSTED, VOIDED
}
}
Address Entity
import lombok.Data;
import javax.persistence.*;
@Entity
@Table(name = "addresses")
@Data
public class Address {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(name = "line1")
private String line1;
@Column(name = "line2")
private String line2;
@Column(name = "line3")
private String line3;
@Column(name = "city")
private String city;
@Column(name = "region")
private String region; // State/Province
@Column(name = "country")
private String country = "US";
@Column(name = "postal_code")
private String postalCode;
@Column(name = "latitude")
private Double latitude;
@Column(name = "longitude")
private Double longitude;
@Column(name = "address_type")
@Enumerated(EnumType.STRING)
private AddressType addressType;
@Column(name = "created_at")
private LocalDateTime createdAt;
@PrePersist
protected void onCreate() {
createdAt = LocalDateTime.now();
}
public enum AddressType {
ORIGIN, DESTINATION, BILLING, SHIPPING, LOCATION
}
}
Tax Line Entity
import lombok.Data;
import javax.persistence.*;
import java.math.BigDecimal;
@Entity
@Table(name = "tax_lines")
@Data
public class TaxLine {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "transaction_id")
private TaxTransaction transaction;
@Column(name = "line_number")
private String lineNumber;
@Column(name = "item_code")
private String itemCode;
@Column(name = "item_description")
private String itemDescription;
@Column(name = "quantity", precision = 10, scale = 4)
private BigDecimal quantity;
@Column(name = "amount", precision = 15, scale = 4)
private BigDecimal amount;
@Column(name = "tax_amount", precision = 15, scale = 4)
private BigDecimal taxAmount;
@Column(name = "tax_code")
private String taxCode;
@Column(name = "discount_amount", precision = 15, scale = 4)
private BigDecimal discountAmount;
@Column(name = "tax_included")
private Boolean taxIncluded = false;
@Column(name = "ref1")
private String ref1;
@Column(name = "ref2")
private String ref2;
@Column(name = "created_at")
private LocalDateTime createdAt;
@PrePersist
protected void onCreate() {
createdAt = LocalDateTime.now();
}
}
4. Data Transfer Objects (DTOs)
Tax Calculation Request DTO
import lombok.Data;
import javax.validation.constraints.*;
import java.math.BigDecimal;
import java.time.LocalDateTime;
import java.util.List;
@Data
public class TaxCalculationRequestDTO {
@NotBlank(message = "Transaction code is required")
private String transactionCode;
@NotNull(message = "Document type is required")
private String documentType; // SalesInvoice, SalesOrder, etc.
private LocalDateTime transactionDate;
@NotBlank(message = "Customer code is required")
private String customerCode;
private String companyCode = "DEFAULT";
@NotNull(message = "Origin address is required")
private AddressDTO originAddress;
@NotNull(message = "Destination address is required")
private AddressDTO destinationAddress;
@NotNull(message = "Lines are required")
@Size(min = 1, message = "At least one line item is required")
private List<LineItemDTO> lines;
private String currencyCode = "USD";
private Boolean commit = false;
private String customerUsageType;
private String businessIdentificationNo;
private String purchaseOrderNo;
private String referenceCode;
@Data
public static class AddressDTO {
@NotBlank(message = "Address line1 is required")
private String line1;
private String line2;
private String line3;
@NotBlank(message = "City is required")
private String city;
@NotBlank(message = "Region is required")
private String region; // State/Province
@NotBlank(message = "Country is required")
private String country = "US";
@NotBlank(message = "Postal code is required")
private String postalCode;
private Double latitude;
private Double longitude;
}
@Data
public static class LineItemDTO {
@NotBlank(message = "Line number is required")
private String lineNumber;
@NotBlank(message = "Item code is required")
private String itemCode;
private String itemDescription;
@NotNull(message = "Quantity is required")
@DecimalMin(value = "0.0", inclusive = false, message = "Quantity must be greater than 0")
private BigDecimal quantity = BigDecimal.ONE;
@NotNull(message = "Amount is required")
@DecimalMin(value = "0.0", message = "Amount must be non-negative")
private BigDecimal amount;
private String taxCode;
private Boolean taxIncluded = false;
private BigDecimal discountAmount = BigDecimal.ZERO;
private String ref1;
private String ref2;
}
}
Tax Calculation Response DTO
import lombok.Data;
import java.math.BigDecimal;
import java.time.LocalDateTime;
import java.util.List;
@Data
public class TaxCalculationResponseDTO {
private String transactionCode;
private String avalaraTransactionId;
private String documentType;
private LocalDateTime transactionDate;
private BigDecimal totalAmount;
private BigDecimal totalTax;
private BigDecimal taxableAmount;
private BigDecimal exemptAmount;
private String currencyCode;
private List<TaxLineDTO> lines;
private List<TaxSummaryDTO> taxSummary;
private List<TaxAddressDTO> addresses;
private String status;
private Boolean commitStatus;
private LocalDateTime taxCalculationDate;
@Data
public static class TaxLineDTO {
private String lineNumber;
private String itemCode;
private String itemDescription;
private BigDecimal quantity;
private BigDecimal amount;
private BigDecimal taxAmount;
private String taxCode;
private BigDecimal discountAmount;
private Boolean taxIncluded;
private List<TaxDetailDTO> taxDetails;
}
@Data
public static class TaxDetailDTO {
private String jurisdictionName;
private String jurisdictionType;
private BigDecimal rate;
private BigDecimal taxAmount;
private BigDecimal taxableAmount;
private String taxName;
private String taxType;
}
@Data
public static class TaxSummaryDTO {
private String country;
private String region;
private String jurisdictionType;
private String taxName;
private BigDecimal rate;
private BigDecimal taxAmount;
private BigDecimal taxableAmount;
}
@Data
public static class TaxAddressDTO {
private String addressType;
private String line1;
private String line2;
private String line3;
private String city;
private String region;
private String country;
private String postalCode;
}
}
Address Validation DTO
import lombok.Data;
import javax.validation.constraints.NotBlank;
@Data
public class AddressValidationRequestDTO {
@NotBlank(message = "Address line1 is required")
private String line1;
private String line2;
private String line3;
@NotBlank(message = "City is required")
private String city;
@NotBlank(message = "Region is required")
private String region;
@NotBlank(message = "Country is required")
private String country = "US";
@NotBlank(message = "Postal code is required")
private String postalCode;
private String textCase = "Mixed"; // Upper, Mixed
private Double latitude;
private Double longitude;
}
5. Avalara API Client Service
Main Avalara Service
import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;
import lombok.extern.slf4j.Slf4j;
import okhttp3.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.cache.annotation.Cacheable;
import org.springframework.stereotype.Service;
import java.io.IOException;
import java.util.Base64;
import java.util.Map;
import java.util.concurrent.TimeUnit;
@Slf4j
@Service
public class AvalaraService {
private final AvalaraConfig config;
private final OkHttpClient httpClient;
private final ObjectMapper objectMapper;
@Autowired
public AvalaraService(AvalaraConfig config, ObjectMapper objectMapper) {
this.config = config;
this.objectMapper = objectMapper;
this.httpClient = new OkHttpClient.Builder()
.connectTimeout(config.getTimeout(), TimeUnit.MILLISECONDS)
.readTimeout(config.getTimeout(), TimeUnit.MILLISECONDS)
.writeTimeout(config.getTimeout(), TimeUnit.MILLISECONDS)
.addInterceptor(new AuthInterceptor(config.getAccountId(), config.getLicenseKey()))
.addInterceptor(new UserAgentInterceptor(config))
.addInterceptor(new RetryInterceptor(config.getMaxRetries(), 1000))
.build();
}
/**
* Create or adjust a transaction
*/
public Map<String, Object> createTransaction(Map<String, Object> transactionRequest) throws AvalaraException {
try {
String jsonBody = objectMapper.writeValueAsString(transactionRequest);
String url = config.getBaseUrl() + "/api/v2/transactions/create";
RequestBody body = RequestBody.create(
jsonBody,
MediaType.parse("application/json")
);
Request request = new Request.Builder()
.url(url)
.post(body)
.build();
String responseBody = executeRequest(request);
return objectMapper.readValue(responseBody, new TypeReference<Map<String, Object>>() {});
} catch (IOException e) {
log.error("Error creating transaction: {}", e.getMessage(), e);
throw new AvalaraException("Failed to create transaction", e);
}
}
/**
* Calculate tax for a transaction
*/
public Map<String, Object> calculateTax(Map<String, Object> taxRequest) throws AvalaraException {
try {
String jsonBody = objectMapper.writeValueAsString(taxRequest);
String url = config.getBaseUrl() + "/api/v2/transactions/create";
// For calculation only, don't save the transaction
url += "?$include=Lines,Details,Summary,Addresses";
RequestBody body = RequestBody.create(
jsonBody,
MediaType.parse("application/json")
);
Request request = new Request.Builder()
.url(url)
.post(body)
.build();
String responseBody = executeRequest(request);
return objectMapper.readValue(responseBody, new TypeReference<Map<String, Object>>() {});
} catch (IOException e) {
log.error("Error calculating tax: {}", e.getMessage(), e);
throw new AvalaraException("Failed to calculate tax", e);
}
}
/**
* Validate an address
*/
@Cacheable(value = "addressValidation", key = "#addressRequest.hashCode()")
public Map<String, Object> validateAddress(Map<String, Object> addressRequest) throws AvalaraException {
try {
String jsonBody = objectMapper.writeValueAsString(addressRequest);
String url = config.getBaseUrl() + "/api/v2/addresses/resolve";
RequestBody body = RequestBody.create(
jsonBody,
MediaType.parse("application/json")
);
Request request = new Request.Builder()
.url(url)
.post(body)
.build();
String responseBody = executeRequest(request);
return objectMapper.readValue(responseBody, new TypeReference<Map<String, Object>>() {});
} catch (IOException e) {
log.error("Error validating address: {}", e.getMessage(), e);
throw new AvalaraException("Failed to validate address", e);
}
}
/**
* Get tax rates by postal code
*/
@Cacheable(value = "taxRates", key = "#postalCode + '_' + #country + '_' + #line1")
public Map<String, Object> getTaxRatesByPostalCode(String postalCode, String country, String line1) throws AvalaraException {
try {
HttpUrl.Builder urlBuilder = HttpUrl.parse(config.getBaseUrl() + "/api/v2/taxrates/bypostalcode").newBuilder();
urlBuilder.addQueryParameter("postalCode", postalCode);
urlBuilder.addQueryParameter("country", country);
if (line1 != null) {
urlBuilder.addQueryParameter("line1", line1);
}
Request request = new Request.Builder()
.url(urlBuilder.build())
.get()
.build();
String responseBody = executeRequest(request);
return objectMapper.readValue(responseBody, new TypeReference<Map<String, Object>>() {});
} catch (IOException e) {
log.error("Error getting tax rates: {}", e.getMessage(), e);
throw new AvalaraException("Failed to get tax rates", e);
}
}
/**
* Void a transaction
*/
public Map<String, Object> voidTransaction(String companyCode, String transactionCode, String documentType) throws AvalaraException {
try {
String url = config.getBaseUrl() + "/api/v2/companies/" + companyCode +
"/transactions/" + transactionCode + "/void";
Map<String, String> voidRequest = Map.of(
"code", "DocVoided"
);
String jsonBody = objectMapper.writeValueAsString(voidRequest);
RequestBody body = RequestBody.create(
jsonBody,
MediaType.parse("application/json")
);
Request request = new Request.Builder()
.url(url)
.post(body)
.build();
String responseBody = executeRequest(request);
return objectMapper.readValue(responseBody, new TypeReference<Map<String, Object>>() {});
} catch (IOException e) {
log.error("Error voiding transaction: {}", e.getMessage(), e);
throw new AvalaraException("Failed to void transaction", e);
}
}
/**
* Get transaction by ID
*/
public Map<String, Object> getTransaction(String companyCode, String transactionCode) throws AvalaraException {
try {
String url = config.getBaseUrl() + "/api/v2/companies/" + companyCode +
"/transactions/" + transactionCode +
"?$include=Lines,Details,Summary,Addresses";
Request request = new Request.Builder()
.url(url)
.get()
.build();
String responseBody = executeRequest(request);
return objectMapper.readValue(responseBody, new TypeReference<Map<String, Object>>() {});
} catch (IOException e) {
log.error("Error getting transaction: {}", e.getMessage(), e);
throw new AvalaraException("Failed to get transaction", e);
}
}
/**
* Create a refund transaction
*/
public Map<String, Object> createRefund(String companyCode, String originalTransactionCode,
Map<String, Object> refundRequest) throws AvalaraException {
try {
String url = config.getBaseUrl() + "/api/v2/companies/" + companyCode +
"/transactions/" + originalTransactionCode + "/refund";
String jsonBody = objectMapper.writeValueAsString(refundRequest);
RequestBody body = RequestBody.create(
jsonBody,
MediaType.parse("application/json")
);
Request request = new Request.Builder()
.url(url)
.post(body)
.build();
String responseBody = executeRequest(request);
return objectMapper.readValue(responseBody, new TypeReference<Map<String, Object>>() {});
} catch (IOException e) {
log.error("Error creating refund: {}", e.getMessage(), e);
throw new AvalaraException("Failed to create refund", e);
}
}
/**
* Ping Avalara service to check connectivity
*/
public Map<String, Object> ping() throws AvalaraException {
try {
Request request = new Request.Builder()
.url(config.getBaseUrl() + "/api/v2/utilities/ping")
.get()
.build();
String responseBody = executeRequest(request);
return objectMapper.readValue(responseBody, new TypeReference<Map<String, Object>>() {});
} catch (IOException e) {
log.error("Error pinging Avalara: {}", e.getMessage(), e);
throw new AvalaraException("Failed to ping Avalara service", e);
}
}
private String executeRequest(Request request) throws IOException, AvalaraException {
try (Response response = httpClient.newCall(request).execute()) {
if (!response.isSuccessful()) {
String errorBody = response.body().string();
log.error("Avalara API error: {} - {}", response.code(), errorBody);
throw new AvalaraException("Avalara API error: " + response.code() + " - " + errorBody);
}
return response.body().string();
}
}
}
Authentication Interceptor
import okhttp3.*;
import org.jetbrains.annotations.NotNull;
import java.io.IOException;
import java.util.Base64;
public class AuthInterceptor implements Interceptor {
private final String credentials;
public AuthInterceptor(String accountId, String licenseKey) {
String auth = accountId + ":" + licenseKey;
this.credentials = "Basic " + Base64.getEncoder().encodeToString(auth.getBytes());
}
@NotNull
@Override
public Response intercept(@NotNull Chain chain) throws IOException {
Request originalRequest = chain.request();
Request authenticatedRequest = originalRequest.newBuilder()
.header("Authorization", credentials)
.build();
return chain.proceed(authenticatedRequest);
}
}
User Agent Interceptor
import okhttp3.*;
import org.jetbrains.annotations.NotNull;
import java.io.IOException;
public class UserAgentInterceptor implements Interceptor {
private final String userAgent;
public UserAgentInterceptor(AvalaraConfig config) {
this.userAgent = String.format("%s/%s (%s; %s; %s)",
config.getAppName(),
config.getAppVersion(),
config.getMachineName(),
"Java",
config.getEnvironment());
}
@NotNull
@Override
public Response intercept(@NotNull Chain chain) throws IOException {
Request originalRequest = chain.request();
Request modifiedRequest = originalRequest.newBuilder()
.header("User-Agent", userAgent)
.header("X-Avalara-Client", userAgent)
.build();
return chain.proceed(modifiedRequest);
}
}
Retry Interceptor
import okhttp3.*;
import org.jetbrains.annotations.NotNull;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.io.IOException;
import java.util.concurrent.TimeUnit;
public class RetryInterceptor implements Interceptor {
private static final Logger logger = LoggerFactory.getLogger(RetryInterceptor.class);
private final int maxRetries;
private final long backoffDelay;
public RetryInterceptor(int maxRetries, long backoffDelay) {
this.maxRetries = maxRetries;
this.backoffDelay = backoffDelay;
}
@NotNull
@Override
public Response intercept(@NotNull Chain chain) throws IOException {
Request request = chain.request();
Response response = null;
IOException exception = null;
for (int attempt = 1; attempt <= maxRetries; attempt++) {
try {
response = chain.proceed(request);
if (response.isSuccessful()) {
return response;
}
// Only retry on server errors (5xx) or rate limiting
if (response.code() < 500 && response.code() != 429) {
return response;
}
logger.warn("Avalara API request failed with status {} on attempt {}/{}",
response.code(), attempt, maxRetries);
} catch (IOException e) {
exception = e;
logger.warn("Avalara API request failed with IOException on attempt {}/{}: {}",
attempt, maxRetries, e.getMessage());
}
if (attempt < maxRetries) {
try {
long delay = backoffDelay * (long) Math.pow(2, attempt - 1);
TimeUnit.MILLISECONDS.sleep(delay);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
throw new IOException("Request interrupted", e);
}
}
if (response != null) {
response.close();
}
}
if (exception != null) {
throw exception;
}
return response;
}
}
6. Tax Processing Service
import com.fasterxml.jackson.databind.ObjectMapper;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import java.math.BigDecimal;
import java.time.LocalDateTime;
import java.util.*;
@Slf4j
@Service
public class TaxProcessingService {
@Autowired
private AvalaraService avalaraService;
@Autowired
private TaxTransactionRepository taxTransactionRepository;
@Autowired
private AddressRepository addressRepository;
@Autowired
private TaxLineRepository taxLineRepository;
@Autowired
private ObjectMapper objectMapper;
/**
* Calculate tax for a transaction
*/
@Transactional
public TaxCalculationResponseDTO calculateTax(TaxCalculationRequestDTO request) throws AvalaraException {
try {
// Prepare Avalara transaction request
Map<String, Object> avalaraRequest = prepareAvalaraTransactionRequest(request, false);
// Call Avalara API
Map<String, Object> avalaraResponse = avalaraService.calculateTax(avalaraRequest);
// Convert response to DTO
TaxCalculationResponseDTO response = convertToTaxResponseDTO(avalaraResponse);
log.info("Tax calculation completed for transaction: {}", request.getTransactionCode());
return response;
} catch (Exception e) {
log.error("Error calculating tax for transaction {}: {}", request.getTransactionCode(), e.getMessage(), e);
throw new AvalaraException("Tax calculation failed: " + e.getMessage(), e);
}
}
/**
* Create and commit a tax transaction
*/
@Transactional
public TaxCalculationResponseDTO createTransaction(TaxCalculationRequestDTO request) throws AvalaraException {
try {
// Prepare Avalara transaction request
Map<String, Object> avalaraRequest = prepareAvalaraTransactionRequest(request, true);
// Call Avalara API
Map<String, Object> avalaraResponse = avalaraService.createTransaction(avalaraRequest);
// Save transaction to database
saveTransactionToDatabase(request, avalaraResponse);
// Convert response to DTO
TaxCalculationResponseDTO response = convertToTaxResponseDTO(avalaraResponse);
log.info("Tax transaction created and committed: {}", request.getTransactionCode());
return response;
} catch (Exception e) {
log.error("Error creating tax transaction {}: {}", request.getTransactionCode(), e.getMessage(), e);
throw new AvalaraException("Transaction creation failed: " + e.getMessage(), e);
}
}
/**
* Validate address using Avalara
*/
public Map<String, Object> validateAddress(AddressValidationRequestDTO request) throws AvalaraException {
try {
Map<String, Object> addressRequest = new HashMap<>();
addressRequest.put("line1", request.getLine1());
addressRequest.put("line2", request.getLine2());
addressRequest.put("line3", request.getLine3());
addressRequest.put("city", request.getCity());
addressRequest.put("region", request.getRegion());
addressRequest.put("country", request.getCountry());
addressRequest.put("postalCode", request.getPostalCode());
addressRequest.put("textCase", request.getTextCase());
if (request.getLatitude() != null && request.getLongitude() != null) {
addressRequest.put("latitude", request.getLatitude());
addressRequest.put("longitude", request.getLongitude());
}
return avalaraService.validateAddress(addressRequest);
} catch (Exception e) {
log.error("Error validating address: {}", e.getMessage(), e);
throw new AvalaraException("Address validation failed: " + e.getMessage(), e);
}
}
/**
* Void a tax transaction
*/
@Transactional
public Map<String, Object> voidTransaction(String companyCode, String transactionCode) throws AvalaraException {
try {
Map<String, Object> voidResponse = avalaraService.voidTransaction(companyCode, transactionCode, "SalesInvoice");
// Update transaction status in database
taxTransactionRepository.findByTransactionCode(transactionCode).ifPresent(transaction -> {
transaction.setStatus(TaxTransaction.TransactionStatus.VOIDED);
taxTransactionRepository.save(transaction);
});
log.info("Transaction voided: {}", transactionCode);
return voidResponse;
} catch (Exception e) {
log.error("Error voiding transaction {}: {}", transactionCode, e.getMessage(), e);
throw new AvalaraException("Transaction voiding failed: " + e.getMessage(), e);
}
}
/**
* Prepare Avalara transaction request
*/
private Map<String, Object> prepareAvalaraTransactionRequest(TaxCalculationRequestDTO request, boolean commit) {
Map<String, Object> avalaraRequest = new HashMap<>();
// Basic transaction info
avalaraRequest.put("code", request.getTransactionCode());
avalaraRequest.put("date", request.getTransactionDate() != null ?
request.getTransactionDate().toString() : LocalDateTime.now().toString());
avalaraRequest.put("customerCode", request.getCustomerCode());
avalaraRequest.put("companyCode", request.getCompanyCode());
avalaraRequest.put("type", request.getDocumentType());
avalaraRequest.put("currencyCode", request.getCurrencyCode());
avalaraRequest.put("commit", commit);
// Addresses
Map<String, Object> addresses = new HashMap<>();
addresses.put("singleLocation", convertAddressToMap(request.getDestinationAddress()));
if (request.getOriginAddress() != null) {
Map<String, Object> addressMap = new HashMap<>();
addressMap.put("shipFrom", convertAddressToMap(request.getOriginAddress()));
addressMap.put("shipTo", convertAddressToMap(request.getDestinationAddress()));
avalaraRequest.put("addresses", addressMap);
} else {
avalaraRequest.put("addresses", addresses);
}
// Lines
List<Map<String, Object>> lines = new ArrayList<>();
for (TaxCalculationRequestDTO.LineItemDTO line : request.getLines()) {
Map<String, Object> lineMap = new HashMap<>();
lineMap.put("number", line.getLineNumber());
lineMap.put("itemCode", line.getItemCode());
lineMap.put("description", line.getItemDescription());
lineMap.put("quantity", line.getQuantity());
lineMap.put("amount", line.getAmount());
lineMap.put("taxCode", line.getTaxCode());
lineMap.put("taxIncluded", line.getTaxIncluded());
lineMap.put("discountAmount", line.getDiscountAmount());
if (line.getRef1() != null) lineMap.put("ref1", line.getRef1());
if (line.getRef2() != null) lineMap.put("Ref2", line.getRef2());
lines.add(lineMap);
}
avalaraRequest.put("lines", lines);
// Additional fields
if (request.getCustomerUsageType() != null) {
avalaraRequest.put("customerUsageType", request.getCustomerUsageType());
}
if (request.getBusinessIdentificationNo() != null) {
avalaraRequest.put("businessIdentificationNo", request.getBusinessIdentificationNo());
}
if (request.getPurchaseOrderNo() != null) {
avalaraRequest.put("purchaseOrderNo", request.getPurchaseOrderNo());
}
if (request.getReferenceCode() != null) {
avalaraRequest.put("referenceCode", request.getReferenceCode());
}
return avalaraRequest;
}
/**
* Convert address DTO to map
*/
private Map<String, Object> convertAddressToMap(TaxCalculationRequestDTO.AddressDTO address) {
Map<String, Object> addressMap = new HashMap<>();
addressMap.put("line1", address.getLine1());
if (address.getLine2() != null) addressMap.put("line2", address.getLine2());
if (address.getLine3() != null) addressMap.put("line3", address.getLine3());
addressMap.put("city", address.getCity());
addressMap.put("region", address.getRegion());
addressMap.put("country", address.getCountry());
addressMap.put("postalCode", address.getPostalCode());
if (address.getLatitude() != null) addressMap.put("latitude", address.getLatitude());
if (address.getLongitude() != null) addressMap.put("longitude", address.getLongitude());
return addressMap;
}
/**
* Convert Avalara response to DTO
*/
@SuppressWarnings("unchecked")
private TaxCalculationResponseDTO convertToTaxResponseDTO(Map<String, Object> avalaraResponse) {
TaxCalculationResponseDTO response = new TaxCalculationResponseDTO();
response.setTransactionCode((String) avalaraResponse.get("code"));
response.setAvalaraTransactionId((String) avalaraResponse.get("id"));
response.setDocumentType((String) avalaraResponse.get("type"));
response.setTotalAmount(convertToBigDecimal(avalaraResponse.get("totalAmount")));
response.setTotalTax(convertToBigDecimal(avalaraResponse.get("totalTax")));
response.setTaxableAmount(convertToBigDecimal(avalaraResponse.get("taxableAmount")));
response.setExemptAmount(convertToBigDecimal(avalaraResponse.get("exemptAmount")));
response.setCurrencyCode((String) avalaraResponse.get("currencyCode"));
response.setStatus((String) avalaraResponse.get("status"));
response.setCommitStatus((Boolean) avalaraResponse.get("committed"));
// Parse transaction date
if (avalaraResponse.get("date") != null) {
response.setTransactionDate(LocalDateTime.parse((String) avalaraResponse.get("date")));
}
// Parse lines
if (avalaraResponse.get("lines") instanceof List) {
List<Map<String, Object>> lines = (List<Map<String, Object>>) avalaraResponse.get("lines");
List<TaxCalculationResponseDTO.TaxLineDTO> taxLines = new ArrayList<>();
for (Map<String, Object> line : lines) {
TaxCalculationResponseDTO.TaxLineDTO taxLine = new TaxCalculationResponseDTO.TaxLineDTO();
taxLine.setLineNumber((String) line.get("number"));
taxLine.setItemCode((String) line.get("itemCode"));
taxLine.setItemDescription((String) line.get("description"));
taxLine.setQuantity(convertToBigDecimal(line.get("quantity")));
taxLine.setAmount(convertToBigDecimal(line.get("amount")));
taxLine.setTaxAmount(convertToBigDecimal(line.get("tax")));
taxLine.setTaxCode((String) line.get("taxCode"));
taxLine.setDiscountAmount(convertToBigDecimal(line.get("discountAmount")));
taxLine.setTaxIncluded((Boolean) line.get("taxIncluded"));
// Parse tax details
if (line.get("details") instanceof List) {
List<Map<String, Object>> details = (List<Map<String, Object>>) line.get("details");
List<TaxCalculationResponseDTO.TaxDetailDTO> taxDetails = new ArrayList<>();
for (Map<String, Object> detail : details) {
TaxCalculationResponseDTO.TaxDetailDTO taxDetail = new TaxCalculationResponseDTO.TaxDetailDTO();
taxDetail.setJurisdictionName((String) detail.get("jurisdictionName"));
taxDetail.setJurisdictionType((String) detail.get("jurisdictionType"));
taxDetail.setRate(convertToBigDecimal(detail.get("rate")));
taxDetail.setTaxAmount(convertToBigDecimal(detail.get("tax")));
taxDetail.setTaxableAmount(convertToBigDecimal(detail.get("taxable")));
taxDetail.setTaxName((String) detail.get("taxName"));
taxDetail.setTaxType((String) detail.get("taxType"));
taxDetails.add(taxDetail);
}
taxLine.setTaxDetails(taxDetails);
}
taxLines.add(taxLine);
}
response.setLines(taxLines);
}
return response;
}
/**
* Save transaction to database
*/
private void saveTransactionToDatabase(TaxCalculationRequestDTO request, Map<String, Object> avalaraResponse) {
try {
// Save transaction
TaxTransaction transaction = new TaxTransaction();
transaction.setTransactionCode(request.getTransactionCode());
transaction.setAvalaraTransactionId((String) avalaraResponse.get("id"));
transaction.setDocumentType(TaxTransaction.DocumentType.valueOf((String) avalaraResponse.get("type")));
transaction.setCustomerCode(request.getCustomerCode());
transaction.setCompanyCode(request.getCompanyCode());
transaction.setTotalAmount(convertToBigDecimal(avalaraResponse.get("totalAmount")));
transaction.setTotalTax(convertToBigDecimal(avalaraResponse.get("totalTax")));
transaction.setTaxableAmount(convertToBigDecimal(avalaraResponse.get("taxableAmount")));
transaction.setExemptAmount(convertToBigDecimal(avalaraResponse.get("exemptAmount")));
transaction.setCurrencyCode(request.getCurrencyCode());
transaction.setStatus(TaxTransaction.TransactionStatus.COMMITTED);
transaction.setCommitStatus(true);
transaction.setTaxCalculationDate(LocalDateTime.now());
taxTransactionRepository.save(transaction);
log.info("Tax transaction saved to database: {}", request.getTransactionCode());
} catch (Exception e) {
log.error("Error saving transaction to database: {}", e.getMessage(), e);
// Don't throw exception to avoid rolling back the Avalara transaction
}
}
/**
* Convert object to BigDecimal safely
*/
private BigDecimal convertToBigDecimal(Object value) {
if (value == null) return BigDecimal.ZERO;
if (value instanceof BigDecimal) return (BigDecimal) value;
if (value instanceof Double) return BigDecimal.valueOf((Double) value);
if (value instanceof Integer) return BigDecimal.valueOf((Integer) value);
if (value instanceof String) return new BigDecimal((String) value);
return BigDecimal.ZERO;
}
}
7. REST Controllers
Tax Controller
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import javax.validation.Valid;
import java.util.HashMap;
import java.util.Map;
@Slf4j
@RestController
@RequestMapping("/api/tax")
public class TaxController {
@Autowired
private TaxProcessingService taxProcessingService;
@Autowired
private AvalaraService avalaraService;
/**
* Calculate tax for a transaction
*/
@PostMapping("/calculate")
public ResponseEntity<?> calculateTax(@Valid @RequestBody TaxCalculationRequestDTO request) {
try {
TaxCalculationResponseDTO response = taxProcessingService.calculateTax(request);
return ResponseEntity.ok(response);
} catch (AvalaraException e) {
log.error("Tax calculation error: {}", e.getMessage(), e);
Map<String, Object> errorResponse = new HashMap<>();
errorResponse.put("error", true);
errorResponse.put("message", "Tax calculation failed");
errorResponse.put("error_description", e.getMessage());
return ResponseEntity.badRequest().body(errorResponse);
}
}
/**
* Create and commit a tax transaction
*/
@PostMapping("/transactions")
public ResponseEntity<?> createTransaction(@Valid @RequestBody TaxCalculationRequestDTO request) {
try {
TaxCalculationResponseDTO response = taxProcessingService.createTransaction(request);
return ResponseEntity.ok(response);
} catch (AvalaraException e) {
log.error("Transaction creation error: {}", e.getMessage(), e);
Map<String, Object> errorResponse = new HashMap<>();
errorResponse.put("error", true);
errorResponse.put("message", "Transaction creation failed");
errorResponse.put("error_description", e.getMessage());
return ResponseEntity.badRequest().body(errorResponse);
}
}
/**
* Validate address
*/
@PostMapping("/addresses/validate")
public ResponseEntity<?> validateAddress(@Valid @RequestBody AddressValidationRequestDTO request) {
try {
Map<String, Object> response = taxProcessingService.validateAddress(request);
return ResponseEntity.ok(response);
} catch (AvalaraException e) {
log.error("Address validation error: {}", e.getMessage(), e);
Map<String, Object> errorResponse = new HashMap<>();
errorResponse.put("error", true);
errorResponse.put("message", "Address validation failed");
errorResponse.put("error_description", e.getMessage());
return ResponseEntity.badRequest().body(errorResponse);
}
}
/**
* Get tax rates by postal code
*/
@GetMapping("/rates")
public ResponseEntity<?> getTaxRates(
@RequestParam String postalCode,
@RequestParam String country,
@RequestParam(required = false) String line1) {
try {
Map<String, Object> response = avalaraService.getTaxRatesByPostalCode(postalCode, country, line1);
return ResponseEntity.ok(response);
} catch (AvalaraException e) {
log.error("Tax rates lookup error: {}", e.getMessage(), e);
Map<String, Object> errorResponse = new HashMap<>();
errorResponse.put("error", true);
errorResponse.put("message", "Tax rates lookup failed");
errorResponse.put("error_description", e.getMessage());
return ResponseEntity.badRequest().body(errorResponse);
}
}
/**
* Void a transaction
*/
@PostMapping("/transactions/{transactionCode}/void")
public ResponseEntity<?> voidTransaction(
@PathVariable String transactionCode,
@RequestParam(defaultValue = "DEFAULT") String companyCode) {
try {
Map<String, Object> response = taxProcessingService.voidTransaction(companyCode, transactionCode);
return ResponseEntity.ok(response);
} catch (AvalaraException e) {
log.error("Transaction voiding error: {}", e.getMessage(), e);
Map<String, Object> errorResponse = new HashMap<>();
errorResponse.put("error", true);
errorResponse.put("message", "Transaction voiding failed");
errorResponse.put("error_description", e.getMessage());
return ResponseEntity.badRequest().body(errorResponse);
}
}
/**
* Ping Avalara service
*/
@GetMapping("/ping")
public ResponseEntity<?> ping() {
try {
Map<String, Object> response = avalaraService.ping();
return ResponseEntity.ok(response);
} catch (AvalaraException e) {
log.error("Avalara ping error: {}", e.getMessage(), e);
Map<String, Object> errorResponse = new HashMap<>();
errorResponse.put("error", true);
errorResponse.put("message", "Avalara service unavailable");
errorResponse.put("error_description", e.getMessage());
return ResponseEntity.status(503).body(errorResponse);
}
}
}
8. Custom Exception
public class AvalaraException extends Exception {
public AvalaraException(String message) {
super(message);
}
public AvalaraException(String message, Throwable cause) {
super(message, cause);
}
}
9. Repository Interfaces
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;
import org.springframework.stereotype.Repository;
import java.math.BigDecimal;
import java.time.LocalDateTime;
import java.util.List;
import java.util.Optional;
@Repository
public interface TaxTransactionRepository extends JpaRepository<TaxTransaction, Long> {
Optional<TaxTransaction> findByTransactionCode(String transactionCode);
Optional<TaxTransaction> findByAvalaraTransactionId(String avalaraTransactionId);
List<TaxTransaction> findByCustomerCode(String customerCode);
List<TaxTransaction> findByCompanyCode(String companyCode);
List<TaxTransaction> findByStatus(TaxTransaction.TransactionStatus status);
List<TaxTransaction> findByTransactionDateBetween(LocalDateTime start, LocalDateTime end);
@Query("SELECT SUM(t.totalTax) FROM TaxTransaction t WHERE t.status = 'COMMITTED' AND t.transactionDate BETWEEN :start AND :end")
BigDecimal getTotalTaxByPeriod(@Param("start") LocalDateTime start, @Param("end") LocalDateTime end);
@Query("SELECT COUNT(t) FROM TaxTransaction t WHERE t.status = 'COMMITTED' AND t.transactionDate BETWEEN :start AND :end")
Long getTransactionCountByPeriod(@Param("start") LocalDateTime start, @Param("end") LocalDateTime end);
}
@Repository
public interface AddressRepository extends JpaRepository<Address, Long> {
List<Address> findByCountry(String country);
List<Address> findByRegion(String region);
List<Address> findByPostalCode(String postalCode);
List<Address> findByAddressType(Address.AddressType addressType);
}
@Repository
public interface TaxLineRepository extends JpaRepository<TaxLine, Long> {
List<TaxLine> findByTransaction(TaxTransaction transaction);
List<TaxLine> findByItemCode(String itemCode);
List<TaxLine> findByTaxCode(String taxCode);
}
This comprehensive Avalara Tax API integration provides complete tax calculation, address validation, transaction management, and compliance features for your Java application.