Announcing the Distilled Avalara AvaTax SDK

Calculate tax, manage transactions, and automate AvaTax from Effect with 470 generated operations.

Sales-tax code sits at an uncomfortable intersection: business-critical, integration-heavy, and unforgiving of silent data-shape mistakes. @kevinmichaelchen/distilled-avalara brings Avalara AvaTax REST v2 into Effect with 470 generated operations and provider-aware runtime policy.

AvaTax, at a glance

Avalara AvaTax automates sales and use tax calculations and related compliance workflows. Its REST v2 surface covers tax calculation, transactions, addresses, exemptions, certificates, filings, reports, jurisdictions, nexus, and account configuration. Avalara publishes developer documentation and SDKs, including its official AvaTax-REST-V2-JS-SDK.

AvaTax product

Avalara’s overview of automated tax calculation.

Official developer SDKs

REST v2 guidance and Avalara-maintained libraries.

Distilled implementation

Credential modes, policy, and 470 generated Effect operations.

Official-spec mirror

The exact official Swagger document used for generation.

Why Effect and Distilled?

Tax calculations are ideal boundary-validation candidates. A request should not drift into production with malformed address or transaction data, and a response should not silently violate the contract your accounting path assumes. Distilled codecs validate both sides. Effect keeps parse failures, Avalara error envelopes, authentication errors, and retryable responses in a typed error channel while making secrets redacted configuration.

That becomes more valuable as a flow grows from a rate estimate into transaction creation, adjustment, commitment, refunding, and reconciliation: the whole workflow shares one retry, tracing, and failure model.

How we made the SDK

Mirror Avalara's Swagger

A dedicated repository stores a formatted-but-semantically-unchanged copy of the official AvaTax REST v2 document.

Pin the source commit

The implementation consumes that repository as a submodule, making every release traceable to one immutable contract.

Generate and review

The shared Alchemy-derived Swagger/OpenAPI generator emits 470 operation modules, committed so changes remain visible in review.

Model Avalara policy explicitly

The handwritten layer supports bearer tokens or account ID and license key authentication, the client header, vendor errors, and rate-limit guidance.

Code Examples

Set either AVALARA_BEARER_TOKEN or AVALARA_ACCOUNT_ID and AVALARA_LICENSE_KEY. Use AVALARA_BASE_URL=https://sandbox-rest.avatax.com for a sandbox account.

npm install @kevinmichaelchen/distilled-avalara effect

pnpm add @kevinmichaelchen/distilled-avalara effect

bun add @kevinmichaelchen/distilled-avalara effect

import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
import {
  createTransaction,
  CredentialsFromEnv,
  getTransactionByCode,
  taxRatesByAddress,
} from "@kevinmichaelchen/distilled-avalara";

const AvaTaxLive = Layer.mergeAll(FetchHttpClient.layer, CredentialsFromEnv);

Estimate the rate for an address

Use the address endpoint for a quick jurisdictional estimate before constructing a transaction.

const estimate = taxRatesByAddress({
  line1: "100 Market Street",
  city: "Philadelphia",
  region: "PA",
  postalCode: "19106",
  country: "US",
});

const estimateAddressRates = estimate.pipe(Effect.provide(AvaTaxLive));

Calculate a sales transaction

Create an uncommitted sales order so AvaTax can account for nexus, sourcing, product taxability, exemptions, and line-level addresses.

const calculateSalesTransaction = createTransaction({
  companyCode: "DEFAULT",
  type: "SalesOrder",
  date: "2026-07-15",
  customerCode: "CUST-1007",
  commit: false,
  lines: [{
    number: "1",
    quantity: 2,
    amount: 199.98,
    taxCode: "P0000000",
    addresses: {
      shipFrom: { line1: "1 Warehouse Way", city: "Newark", region: "NJ", postalCode: "07102", country: "US" },
      shipTo: { line1: "100 Market Street", city: "Philadelphia", region: "PA", postalCode: "19106", country: "US" },
    },
  }],
}).pipe(Effect.provide(AvaTaxLive));

Retrieve a transaction for reconciliation

Look up a previously calculated document by the identifiers stored in an order or accounting system.

const retrieveTransaction = getTransactionByCode({
  companyCode: "DEFAULT",
  transactionCode: "ORDER-10492",
  documentType: "SalesOrder",
  $include: "Lines,Details",
}).pipe(Effect.provide(AvaTaxLive));

All operation functions use lower camelCase; their input and output schemas use PascalCase.

Available now

Start with the AvaTax SDK guide, inspect the implementation, or install @kevinmichaelchen/distilled-avalara.