banner iconIntroducing Bloom: Build Medusa stores with AI
Overview
Icon for Avalara

Avalara

Handle taxes using the Avalara API (community integration)

Medusa Avalara Plugin

A Medusa plugin for integrating Avalara AvaTax as a tax provider, enabling automated tax calculations and compliance for your e-commerce store. Created and maintained by u11d.

Table of Contents

  • Features
  • Quick Start
  • Configuration Options
  • Advanced Usage
  • How the plugin works?
  • Troubleshooting
  • Need help?
  • Contributing
  • License

Features

  • Real-time Tax Calculations: Automatically calculate accurate taxes during checkout using Avalara's AvaTax API
  • Order Transaction Management: Create AvaTax transactions when orders are placed for proper tax recording
  • Transaction Lifecycle Tracking:
    • Commit transactions when orders are completed/fulfilled
    • Void transactions when orders are canceled
  • Flexible Configuration: Support for custom tax codes, exemptions (entity use code) and shipping addresses.
  • Address Validation: Validate and standardize shipping addresses using Avalara's address validation service

Quick Start

1. Installation

# npm
npm install @u11d/medusa-avalara
# yarn
yarn add @u11d/medusa-avalara

2. Basic Medusa Config

Add the plugin to your Medusa config file (Copy to clipboardmedusa-config.ts) using the Copy to clipboardwithAvalaraPlugin helper:

import { defineConfig } from "@medusajs/framework/utils";
import { withAvalaraPlugin, AvalaraPluginOptions } from "@u11d/medusa-avalara";


const avalaraPluginOptions: AvalaraPluginOptions = {
  accountId: 0, // Your Avalara account ID
  licenseKey: "YOUR_LICENSE_KEY",
  environment: "sandbox",
  companyId: 0, // Your Avalara company ID
  companyCode: "DEFAULT",
  defaultTaxCode: "PC040100", // Clothing and related products (business-to-customer)-general
};


module.exports = defineConfig(
  withAvalaraPlugin(
    {
      projectConfig: {
        // your project config
      },
      plugins: [
        // other plugins
Important Notes:

  • It's strongly recommended to call Copy to clipboardPOST /store/carts/${cartId}/taxes (docs) before checkout to ensure taxes are recalculated correctly. Medusa doesn't automatically recalculate taxes when cart properties change (quantity, address, discounts), which can lead to incorrect amounts. See issue #13929
  • The Copy to clipboardwithAvalaraPlugin wrapper handles plugin modules registration and dependency injection automatically. See Manual Module Registration section if you need to understand what the helper does or configure modules manually
  • You can use environment variables instead of hardcoding options, especially important for credentials like Copy to clipboardaccountId and Copy to clipboardlicenseKey
  • The example above will use Copy to clipboardPC040100 for each product. See Advanced Usage for assigning specific tax codes to individual products
  • The plugin automatically syncs your Medusa stock locations with Avalara locations on startup for accurate tax calculations. However, since Medusa doesn't emit events for stock location changes, if you create or update a location after startup, you'll need to either restart the app or manually call Copy to clipboardPOST /admin/avalara-cache/feed to refresh the cache
  • The plugin fully supports tax-inclusive pricing and automatically respects the region's tax-inclusive preferences
  • The region's Copy to clipboardAutomatic Taxes configuration is critical for API efficiency. When enabled, Medusa calls the tax provider's Copy to clipboardgetTaxLines method multiple times during the checkout flow (on shipping address updates, shipping method selection, etc.), which significantly increases the number of requests to the Avalara API. To optimize performance and reduce API calls, it's recommended to disable automatic taxes and instead manually trigger tax calculation by calling POST Copy to clipboard/store/carts/{id}/taxes from your storefront when the order is ready for review — typically after the shipping method has been selected.
  • Discounts should be used with caution. Medusa does not use the exact tax amounts returned by Avalara but instead calculates taxes using the rates provided, which may lead to minor differences in final tax calculations when discounts are applied.

3. Run Database Migration

After configuring your Medusa setup, run the database migration to create the required tables:

npx medusa db:migrate

4. Enable AvaTax Provider

After starting your Medusa server:

  1. Go to your admin panel (locally available at Copy to clipboardhttp://localhost:9000/app by default)
  2. Navigate to Settings > Tax Regions
  3. Select a tax region and edit it
  4. Select Avalara as your tax provider
  5. Save the configuration
Note: To disable Avalara and return to the default Medusa tax calculations, simply select System as your tax provider in the same settings.

Configuration Options

Access your Avalara dashboard to obtain the required credentials:

Option Type Required Default Description Copy to clipboardaccountId Copy to clipboardnumber ✅ - Your Avalara account ID Copy to clipboardlicenseKey Copy to clipboardstring ✅ - Your Avalara license key Copy to clipboardenvironment Copy to clipboard"sandbox" | "production" ✅ - AvaTax environment Copy to clipboardcompanyCode Copy to clipboardstring ✅ - Your company code in AvaTax Copy to clipboardcompanyId Copy to clipboardnumber ✅ - Your Avalara company ID Copy to clipboarddocumentRecordingEnabled Copy to clipboardboolean ❌ Copy to clipboardtrue Controls whether documents should be recorded in AvaTax. If set to Copy to clipboardfalse transactions (sales invoices) are not created Copy to clipboardmachineName Copy to clipboardstring ❌ - Machine identifier Copy to clipboarddefaultTaxCode Copy to clipboardstring ❌ - Default tax code for products Copy to clipboardshippingTaxCode Copy to clipboardstring ❌ Copy to clipboard"FR020100" Tax code for shipping

Advanced Usage

Authentication for Admin API Endpoints

The configuration endpoints for managing product tax codes and customer exemptions require admin credentials. You'll need to authenticate first to get a Bearer token that you'll use for subsequent API requests.

Get Authentication Token:

curl -X POST http://localhost:9000/auth/user/emailpass \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your_admin_email@example.com",
    "password": "your_admin_password"
  }'

This will return a response containing a Copy to clipboardtoken field. Copy this token value to use in the Copy to clipboardAuthorization: Bearer YOUR_TOKEN_HERE header for the admin API endpoints described below.

Using Different Tax Codes for Products

In most e-commerce scenarios, different products require different tax codes based on their category, material, or intended use. The plugin uses the Copy to clipboardavalara_product table to determine which specific Avalara tax code should be applied to each product during tax calculations. You can manage these product-specific tax codes either by updating the database table directly or by using the provided admin API endpoint.

You can find the complete list of available Avalara tax codes at: https://taxcode.avatax.avalara.com/

By default, all products will use the Copy to clipboardtaxCodes.default value. To assign specific Avalara tax codes to individual products, make a Copy to clipboardPUT request to Copy to clipboard/admin/avalara-products using your authentication token:

Update Product Tax Codes:

curl -X PUT http://localhost:9000/admin/avalara-products \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "avalara_products": [
      {
        "product_id": "prod_123",
        "tax_code": "PC040100"
      },
      {
        "product_id": "prod_456",
        "tax_code": "PS081000"
      }
    ]
  }'

Customer Tax Exemptions (Entity Use Codes)

Many businesses need to support tax-exempt customers such as government entities, non-profit organizations, or resellers. The plugin provides a complete system for managing customer exemptions through Avalara's Entity Use Codes.

You can find the complete list of predefined Avalara entity use codes at: https://help.avalara.com/Avalara_AvaTax_Update/Entity_Use_Codes

Managing Customer Exemptions

The plugin automatically manages customer exemptions through the Copy to clipboardavalara_customer module, which stores entity use codes for exempt customers and caches them for fast lookup during tax calculations.

Setting Customer Exemptions:

curl -X PUT http://localhost:9000/admin/avalara-customers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "avalara_customers": [
      {
        "customer_id": "cus_federal_agency",
        "entity_use_code": "A"
      },
      {
        "customer_id": "cus_nonprofit",
        "entity_use_code": "E"
      }
    ]
  }'

Listing Customer Exemptions:

curl -X GET "http://localhost:9000/admin/avalara-customers?offset=0&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Address Validation

The plugin provides a Copy to clipboardPOST /store/avalara-address endpoint that serves as a proxy to Avalara's ResolveAddressPost API. Address validation is critical for accurate tax calculations, as Avalara requires correctly formatted and validated addresses to determine proper tax rates and jurisdictions.

Request Body:

{
  "line1": "512 S Mangum St Ste 100",
  "city": "Durham",
  "region": "NC",
  "postalCode": "27701",
  "country": "US"
}

Notes:

Manual Module Registration

If you prefer to configure modules manually without using the Copy to clipboardwithAvalaraPlugin wrapper, you can register each module individually:

import { defineConfig, Modules } from "@medusajs/framework/utils";
import { AvalaraPluginOptions } from "@u11d/medusa-avalara";


const options: AvalaraPluginOptions = {
  // your options here
};


module.exports = defineConfig({
  plugins: ["@u11d/medusa-avalara"],
  modules: [
    {
      resolve: "@u11d/medusa-avalara/modules/avalara-product",
      dependencies: [Modules.CACHE],
    },
    {
      resolve: "@u11d/medusa-avalara/modules/avalara-customer",
      dependencies: [Modules.CACHE],
    },
    {
      resolve: "@u11d/medusa-avalara/modules/avatax-factory",
Note: Manual registration requires careful attention to module dependencies and isolation. The Copy to clipboardwithAvalaraPlugin wrapper is recommended as it handles these complexities automatically.

How the plugin works?

The Medusa Avalara plugin integrates with Avalara's AvaTax service through a modular architecture:

Core Components

modules/avalara-product

  • Manages product-specific tax codes through the Copy to clipboardAvalaraProduct model and database migration
  • Used by the Copy to clipboard/admin/avalara-products API endpoint
  • Saves mapping of Copy to clipboardproduct_id → Copy to clipboardavalara_tax_code in cache for fast retrieval by the AvaTax provider

modules/avalara-customer

  • Manages customer-specific tax exemptions through the Copy to clipboardAvalaraCustomer model and database migration
  • Used by the Copy to clipboard/admin/avalara-customers API endpoint
  • Saves mapping of Copy to clipboardcustomer_id → Copy to clipboardentity_use_code in cache for fast retrieval by the AvaTax provider
  • Validates entity use codes against Avalara's predefined list and provides warnings for unrecognized codes

modules/avatax-factory

  • Provides AvaTax client configured with plugin options
  • Validates plugin options and credentials
  • Validates communication with Avalara to ensure credentials are correct (validation happens in loader)

providers/avatax

  • Tax calculation provider implementation (separate from Copy to clipboardavatax-factory due to Medusa's module isolation requirements)
  • Skips tax calculation if shipping address is not provided
  • Retrieves Copy to clipboardavalara_tax_code from cache; uses default tax code or throws error if not found
  • Makes API calls to AvaTax to create Copy to clipboardSalesOrder entities (temporary entities for dynamic cart tax calculations)
  • The Copy to clipboardgetTaxLines method handles tax rate calculations using the AvaTax API

Order Lifecycle Integration

Subscribers and Workflows:

  • orderPlacedHandler: Creates Sales Invoices (permanent entities representing finalized transactions in Avalara)
  • orderCanceledHandler: Voids the transaction in Avalara
  • orderCompletedHandler: Commits the transaction in Avalara

This architecture ensures accurate tax calculations during checkout and proper transaction lifecycle management in Avalara's system. The Copy to clipboardwithAvalaraPlugin wrapper simplifies the setup by automatically configuring all these modules with proper dependencies and isolation.

Cached Data

The plugin uses Redis cache to store frequently accessed data for optimal performance during tax calculations. This cache strategy minimizes database queries and API calls, ensuring fast response times during checkout.

Product Tax Codes (Copy to clipboardavalara:product:{product_id})

  • Stores the mapping of Medusa product IDs to Avalara tax codes
  • Fed by the Copy to clipboardfeed-avalara-product-cache workflow step
  • Retrieved during tax calculations to determine the appropriate tax code for each line item
  • Falls back to Copy to clipboardtaxCodes.default if no product-specific code is found

Customer Exemptions (Copy to clipboardavalara:customer:{customer_id})

  • Stores entity use codes for tax-exempt customers
  • Fed by the Copy to clipboardfeed-avalara-customer-cache workflow step
  • Retrieved during tax calculations to apply exemptions when applicable
  • Enables quick lookup of customer tax exemption status without database queries

Tax-Inclusive Settings (Copy to clipboardavalara:tax_included:{country_code})

  • Stores whether prices are tax-inclusive for each country
  • Fed by the Copy to clipboardfeed-avalara-tax-inclusive-cache workflow step
  • Based on region price preferences configured in Medusa
  • Critical for correctly calculating taxes in regions with tax-inclusive pricing

Location Mappings (Copy to clipboardavalara:location:{country_code} and Copy to clipboardavalara:location:{country_code}_{province_code})

  • Stores the mapping of geographic locations to Avalara location codes and addresses
  • Fed by the Copy to clipboardfeed-avalara-location-cache workflow step
  • Syncs Medusa stock locations with Avalara locations for accurate origin-based tax calculations
  • Supports both country-level and province/state-level location mappings for precise nexus determination

Cache Management:

  • All cache entries use a 30-day TTL (Time To Live)
  • The cache is automatically populated on application startup through the Copy to clipboardinit-feed-avalara-cache job
  • The cache is automatically refreshed every night at midnight via the Copy to clipboardfeed-avalara-cache scheduled job
  • Cache can be manually refreshed anytime via the Copy to clipboardPOST /admin/avalara-cache/feed endpoint
  • Individual module caches are also refreshed after bulk updates via their respective admin endpoints (e.g., after updating product tax codes or customer exemptions)

Troubleshooting

Migration Error: "relation ... does not exist"

If you encounter any of the following errors:

error: Failed to feed cache. Error: select "a0".* from "public"."avalara_product" as "a0" where "a0"."deleted_at" is null order by "a0"."created_at" desc limit 1000 - relation "public.avalara_product" does not exist. Please make sure migration adding avalara_product table has been run and cache module is injected to the module via medusa-config
Failed to feed cache. Error: select "a0".* from "public"."avalara_customer" as "a0" where "a0"."deleted_at" is null order by "a0"."created_at" desc limit 1000 - relation "public.avalara_customer" does not exist. Please make sure migration adding avalara_customer table has been run and cache module is injected to the module via medusa-config.

Solution: Run the database migration:

npx medusa db:migrate

This ensures the Copy to clipboardavalara_product table is created and the cache module is properly configured.

Tax calculations returning $0

If you're seeing $0 tax amounts in your calculations, follow these troubleshooting steps:

  1. Check application logs for any error messages or warnings related to AvaTax API calls
  2. Verify shipping address - tax calculation is skipped if no valid shipping address is provided
  3. Validate Avalara account configuration:
    • Ensure your company location is properly configured in your Avalara account
    • Verify that tax jurisdictions are set up correctly for your business locations
    • Check that your company has nexus configured for the relevant states/regions
  4. Test tax calculation directly in Avalara:
    • Log into your Avalara account
    • Use the AvaTax API testing tools to verify tax calculations work with your setup
    • Test with the same addresses and product codes you're using in Medusa
  5. Review tax codes:
    • Ensure products have valid Avalara tax codes assigned
    • Verify that the tax codes are appropriate for your products and jurisdiction
  6. Check environment settings:
    • Confirm you're using the correct environment (sandbox vs production)
    • Verify your API credentials are valid and have the necessary permissions

Need help?

If you encounter any issues or need assistance with this plugin, please visit our GitHub Issues page. Our team actively monitors and responds to bug reports, feature requests, and questions from the community. We aim to provide timely support to ensure your integration with Avalara runs smoothly.

Need expert assistance or want our team to support your Medusa project? We're here to help! Contact us at https://u11d.com/contact/ for professional support and consultation services.

Learn More

Read our comprehensive blog article about integrating Avalara with Medusa: https://u11d.com/blog/automated-tax-calculations-medusa-avalara-integration

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

You may also like

Browse all integrations

Build your own

Develop your own custom integraiton

Build your own integration with our API to speed up your processes. Make your integration available via npm for it to be shared in our Library with the broader Medusa community.

payment iconcart icongift icon
Get started
gift card interface

Ready to build your custom commerce setup?

Starter DocsGet started