Skip to main content
If you use Stripe as your invoice provider, Avalara integrates through Stripe rather than directly with Metronome through the Avalara AvaTax app from the Stripe App Marketplace. This uses Stripe’s third-party tax app framework for inline tax calculation.

​
Prerequisites

  1. Install the Avalara AvaTax app in your Stripe dashboard. Connect your Avalara account to Stripe and verify the connection in both dashboards. See Avalara’s Stripe integration page for Avalara-side configuration.
  2. In the Stripe Dashboard, go to 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 in the applicable jurisdictions for sales tax, VAT, and GST.
  3. Connect your Stripe account to Metronome.
  4. Link each Metronome customer to their Stripe customer ID.
  5. Ensure each Stripe customer has a Customer Address set and is marked as Taxable.
The Customer Address field is the address object on the Stripe Customer object, which determines tax jurisdiction. Failure to assign a Customer Address results in failure to apply tax.

​
Step 1: Create TaxCode custom field

To pass tax metadata from Metronome to Stripe:
  1. Create a custom field on the Product entity in Metronome named TaxCode (exact casing is required by Avalara’s metadata specification).
  2. For each product, set the TaxCode value to the corresponding Avalara tax code. Browse available codes at the Avalara tax code catalog.

​
Step 2: Create entity mappings

  1. Go to Connections > Integrations > Stripe > Edit Mapping.
  2. Add the following mapping:
Stripe vendor entityStripe vendor keyMetronome entityMetronome key
invoiceitem.metadataTaxCodeContractProductTaxCode
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.
  1. Click Save.

​
Step 3: Configure invoice settings

Set “Leave invoices as drafts” to ON in your Stripe integration settings (under Connections > Integrations > Stripe > Settings).
Avalara requires invoices to remain in draft so it can calculate and apply tax before finalization.

​
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.
  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 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. 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.