@arraypress/stripe-tax-codes

Stripe tax code categories for e-commerce. Curated common categories with friendly labels, plus utilities for lookup and custom categories. Zero dependencies.

Works in Node.js, Cloudflare Workers, Deno, Bun, and browsers.

Installation

npm install @arraypress/stripe-tax-codes

Usage

import {
  TAX_CATEGORIES,
  getCategory,
  getStripeTaxCode,
  isTaxExempt,
  getCategories,
  getCategoriesGrouped,
} from '@arraypress/stripe-tax-codes';

// Look up a category
const cat = getCategory('digital');
// => { id: 'digital', label: 'Digital Goods', description: '...', stripeTaxCode: 'txcd_10010001', exempt: false }

// Get the Stripe tax code for checkout
const taxCode = getStripeTaxCode('clothing');
// => 'txcd_20010001'

// Check if something is tax exempt
isTaxExempt('gift_card'); // true
isTaxExempt('electronics'); // false

// Get all taxable categories
const taxable = getCategories({ exempt: false });

// Get categories grouped for a UI dropdown
const groups = getCategoriesGrouped();
// groups.digital   => [{ id: 'digital', ... }, { id: 'saas', ... }, ...]
// groups.physical  => [{ id: 'clothing', ... }, { id: 'electronics', ... }, ...]
// groups.services  => [{ id: 'consulting', ... }, { id: 'education', ... }]
// groups.other     => [{ id: 'general', ... }, { id: 'exempt', ... }, ...]

With Stripe Checkout

import Stripe from 'stripe';
import { getStripeTaxCode } from '@arraypress/stripe-tax-codes';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

const session = await stripe.checkout.sessions.create({
  line_items: [{
    price_data: {
      currency: 'usd',
      product: 'prod_xxx',
      unit_amount: 2999,
      tax_behavior: 'exclusive',
    },
    quantity: 1,
    tax_rates: [],
    // Use the Stripe tax code from the category
    dynamic_tax_rates: [],
  }],
  // Or set tax code on the Stripe Product
  // product.tax_code = getStripeTaxCode('clothing')
});

Categories

ID	Label	Stripe Tax Code	Exempt
general	General	txcd_99999999	No
exempt	Tax Exempt	txcd_00000000	Yes
digital	Digital Goods	txcd_10010001	No
saas	SaaS / Cloud Services	txcd_10103001	No
digital_audio	Digital Audio	txcd_10201000	No
digital_video	Digital Video	txcd_10202000	No
digital_books	Digital Books	txcd_10301000	No
digital_games	Digital Games	txcd_10401000	No
digital_images	Digital Images	txcd_10501000	No
physical	Physical Goods	txcd_99999999	No
clothing	Clothing & Apparel	txcd_20010001	No
food_grocery	Groceries	txcd_40030000	No
food_prepared	Prepared Food	txcd_40060003	No
food_supplements	Dietary Supplements	txcd_40050001	No
electronics	Electronics	txcd_34021000	No
furniture	Furniture	txcd_20060000	No
health_beauty	Health & Beauty	txcd_40050000	No
books_physical	Physical Books	txcd_35010000	No
toys	Toys & Games	txcd_20080000	No
jewelry	Jewelry & Watches	txcd_20070000	No
sports	Sports & Outdoors	txcd_20090000	No
pet_supplies	Pet Supplies	txcd_20100000	No
education	Educational Materials	txcd_10502001	No
gift_card	Gift Cards	txcd_10502000	Yes
consulting	Consulting Services	txcd_19003001	No
infrastructure	Infrastructure as a Service	txcd_10101000	No

API Reference

TAX_CATEGORIES

Array of all built-in tax categories. Each entry has id, label, description, stripeTaxCode, and exempt fields.

getCategory(categoryId)

Get a tax category by its ID. Returns the TaxCategory object or undefined.

getStripeTaxCode(categoryId)

Get the Stripe tax code string (e.g. txcd_20010001) for a category ID. Returns undefined if not found.

isTaxExempt(categoryId)

Check if a category is tax exempt. Returns false for unknown category IDs.

getCategories(filter?)

Get all categories, optionally filtered. Pass { exempt: true } for exempt-only or { exempt: false } for taxable-only.

getCategoriesGrouped()

Get categories grouped into digital, physical, services, and other arrays. Useful for building grouped dropdown menus.

License

MIT