> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metronome.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Avalara

> Learn how to configure Avalara AvaTax as your tax provider with Metronome and Stripe invoicing.

If you use **Stripe** as your invoice provider, Avalara integrates through Stripe rather than directly with Metronome through the [Avalara AvaTax app](https://marketplace.stripe.com/apps/avalara-avatax) from the Stripe App Marketplace. This uses Stripe's [third-party tax app framework](https://docs.stripe.com/tax/third-party-apps) for inline tax calculation.

## Prerequisites

1. Install the [**Avalara AvaTax app**](https://marketplace.stripe.com/apps/avalara-avatax) in your Stripe dashboard. Connect your Avalara account to Stripe and verify the connection in both dashboards. See [Avalara's Stripe integration page](https://www.avalara.com/us/en/products/integrations/stripe-invoicing.html) for Avalara-side configuration.
2. In the Stripe Dashboard, go to [**Settings > Tax > Integrations**](https://dashboard.stripe.com/settings/tax/integrations) and confirm Avalara is selected as your tax calculation provider and that "Use automatic tax" is toggled **ON**.
   1. [Complete tax registration](https://docs.stripe.com/tax/registering) in the applicable jurisdictions for sales tax, VAT, and GST.
3. [Connect your Stripe account](/integrations/invoice-integrations/stripe) to Metronome.
4. Link each Metronome customer to their Stripe customer ID.
5. Ensure each Stripe customer has a [**Customer Address**](https://docs.stripe.com/api/customers/object#customer_object-address) set and is marked as **Taxable**.

<Note>
  The Customer Address field is the `address` object on the [Stripe Customer object](https://docs.stripe.com/api/customers/object#customer_object-address), which determines tax jurisdiction. Failure to assign a Customer Address results in failure to apply tax.
</Note>

## Step 1: Create TaxCode custom field

To pass tax metadata from Metronome to Stripe:

1. Create a [custom field](/api-reference/custom-fields) on the **Product** entity in Metronome named `TaxCode` (exact casing is required by [Avalara's metadata specification](https://knowledge.avalara.com/bundle/ymp1659710033243_ymp1659710033243/page/Invoice_line_item_metadata.html)).
2. For each product, set the `TaxCode` value to the corresponding Avalara tax code. Browse available codes at the [Avalara tax code catalog](https://taxcode.avatax.avalara.com/).

## Step 2: Create entity mappings

1. Go to **Connections > Integrations > Stripe > Edit Mapping**.
2. Add the following mapping:

| Stripe vendor entity   | Stripe vendor key | Metronome entity  | Metronome key |
| ---------------------- | ----------------- | ----------------- | ------------- |
| `invoiceitem.metadata` | `TaxCode`         | `ContractProduct` | `TaxCode`     |

<Note>
  If a line item does not have a specified tax code, the standard state sales tax will apply for the customer's jurisdiction. Explicitly setting tax codes ensures accurate classification.
</Note>

3. Click **Save**.

## Step 3: Configure invoice settings

Set **"Leave invoices as drafts"** to **ON** in your Stripe integration settings (under **Connections > Integrations > Stripe > Settings**).

<Note>
  Avalara requires invoices to remain in draft so it can calculate and apply tax before finalization.
</Note>

## Test your configuration

1. Use your **Metronome sandbox** (connected to your **Stripe Sandbox**) to test.
2. Create a customer with a valid Stripe customer ID and [Customer Address](https://docs.stripe.com/api/customers/object#customer_object-address).
3. Generate an invoice in Metronome and view the draft invoice in Stripe.
4. Confirm the tax line items appear on the finalized Stripe invoice after Avalara processes it.

## FAQ and troubleshooting

**Q: My invoices are failing or are finalizing without tax -- what should I check?**

Start by confirming that the Stripe customer has sufficient location information to accurately calculate tax rates for the customer. Ensure both the [Customer Address](https://docs.stripe.com/api/customers/object#customer_object-address) and tax location are set. Then verify that the "Leave invoices as drafts" setting is **ON** in your Stripe integration settings, and that your entity mapping is configured with `TaxCode` values on your Metronome products.

If everything looks correct, contact your Metronome representative to verify your tax setup.

**Q: Tax is being calculated, but the rate seems wrong or is showing as 0%.**

Avalara determines tax rates based on the customer's address and the tax code assigned to the line item. Some products—like SaaS in certain states—may be tax-exempt, which results in a 0% rate. Verify the tax code you've assigned by checking the [Avalara tax code catalog](https://taxcode.avatax.avalara.com/).

If the rate still seems incorrect, contact Avalara support directly, as tax rate accuracy is managed on their side.

**Q: What happens if I don't assign a `TaxCode` to a product?**

If a line item doesn't have a `TaxCode` set in its metadata, Avalara applies a default tax rate. This may result in incorrect tax classification. It's best practice to always assign an explicit tax code.

**Q: Do I need to set a default tax behavior in Stripe?**

In the Stripe dashboard, make sure that you have a default tax behavior selected to ensure tax is correctly added to each invoice.