@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