tessl/npm-stripe

Stripe API wrapper for Node.js providing comprehensive payment processing, subscription management, and financial services integration.

—

Pending

Overview

Eval results

Files

Tax

Name: tessl/npm-stripe
Author: tessl

Stripe Tax provides comprehensive tax calculation, collection, and compliance capabilities for global transactions. It handles complex tax scenarios including VAT, GST, sales tax, and other regional tax requirements with real-time calculation and automated compliance features.

Tax Calculation

Tax.Calculations

Calculate taxes for transactions before creating charges or invoices:

interface TaxCalculation {
  id: string;
  object: 'tax.calculation';
  amount_total: number;
  currency: string;
  customer?: string;
  customer_details: {
    address: {
      country: string;
      state?: string;
      postal_code?: string;
      city?: string;
      line1?: string;
      line2?: string;
    };
    address_source: 'billing' | 'shipping';
    ip_address?: string;
    taxability_override: 'none' | 'reverse_charge' | 'exempt';
  };
  line_items: {
    data: Array<{
      id: string;
      amount: number;
      amount_tax: number;
      product?: string;
      quantity: number;
      reference?: string;
      tax_behavior: 'inclusive' | 'exclusive';
      tax_breakdown: Array<{
        amount: number;
        jurisdiction: {
          country: string;
          display_name: string;
          level: 'country' | 'state' | 'county' | 'city';
          state?: string;
        };
        sourcing: 'destination' | 'origin';
        tax_rate_details: {
          country: string;
          percentage_decimal: string;
          state?: string;
          tax_type: 'gst' | 'hst' | 'pst' | 'qst' | 'rst' | 'sales_tax' | 'vat';
        };
        taxability_reason: 'not_collecting' | 'not_subject_to_tax' | 'not_supported' | 'portion_product_exempt' | 'portion_reduced_rated' | 'portion_standard_rated' | 'product_exempt' | 'product_exempt_holiday' | 'proportionally_rated' | 'reduced_rated' | 'reverse_charge' | 'standard_rated' | 'taxable_basis_reduced' | 'zero_rated';
      }>;
    }>;
  };
  shipping_cost?: {
    amount: number;
    amount_tax: number;
  };
  expires_at?: number;
}

// Calculate tax for line items
const calculation = await stripe.tax.calculations.create({
  currency: 'usd',
  line_items: [
    {
      amount: 1000,
      reference: 'L1',
      tax_behavior: 'exclusive'
    }
  ],
  customer_details: {
    address: {
      line1: '123 Main St',
      city: 'San Francisco',
      state: 'CA',
      postal_code: '94105',
      country: 'US'
    },
    address_source: 'billing'
  }
});

// Calculate with products
const productCalculation = await stripe.tax.calculations.create({
  currency: 'usd',
  line_items: [
    {
      amount: 2000,
      product: 'prod_123',
      quantity: 1,
      tax_behavior: 'exclusive'
    }
  ],
  customer_details: {
    address: {
      country: 'GB',
      postal_code: 'SW1A 1AA'
    },
    address_source: 'shipping'
  }
});

// Calculate with shipping
const shippingCalculation = await stripe.tax.calculations.create({
  currency: 'eur',
  line_items: [
    {
      amount: 5000,
      reference: 'item-1',
      tax_behavior: 'exclusive'
    }
  ],
  shipping_cost: {
    amount: 500
  },
  customer_details: {
    address: {
      country: 'DE',
      postal_code: '10115'
    },
    address_source: 'shipping'
  }
});

// Retrieve calculation
const retrieved = await stripe.tax.calculations.retrieve('taxcalc_123');

// List line items
const lineItems = await stripe.tax.calculations.listLineItems('taxcalc_123');

Tax Transactions

Tax.Transactions

Record and manage tax transactions for compliance:

interface TaxTransaction {
  id: string;
  object: 'tax.transaction';
  type: 'reversal' | 'transaction';
  reference: string;
  currency: string;
  customer?: string;
  customer_details: {
    address: {
      country: string;
      state?: string;
      postal_code?: string;
      city?: string;
      line1?: string;
      line2?: string;
    };
    address_source: 'billing' | 'shipping';
    ip_address?: string;
    taxability_override: 'none' | 'reverse_charge' | 'exempt';
  };
  line_items: {
    data: Array<{
      id: string;
      amount: number;
      amount_tax: number;
      product?: string;
      quantity: number;
      reference: string;
      reversal?: {
        original_line_item: string;
      };
    }>;
  };
  created: number;
}

// Create transaction from calculation
const transaction = await stripe.tax.transactions.createFromCalculation({
  calculation: 'taxcalc_123',
  reference: 'order_12345'
});

// Create transaction directly
const directTransaction = await stripe.tax.transactions.create({
  currency: 'usd',
  line_items: [
    {
      amount: 1000,
      amount_tax: 80,
      reference: 'L1',
      quantity: 1,
      tax_behavior: 'exclusive'
    }
  ],
  customer_details: {
    address: {
      country: 'US',
      state: 'CA',
      postal_code: '94105'
    },
    address_source: 'billing'
  },
  reference: 'invoice_67890'
});

// Retrieve transaction
const retrievedTx = await stripe.tax.transactions.retrieve('tax_123');

// Create reversal
const reversal = await stripe.tax.transactions.createReversal('tax_123', {
  mode: 'full',
  reference: 'refund_123'
});

// Partial reversal
const partialReversal = await stripe.tax.transactions.createReversal('tax_123', {
  mode: 'partial',
  line_items: [
    {
      line_item: 'taxli_123',
      quantity: 1
    }
  ],
  reference: 'partial_refund_456'
});

// List transactions
const transactions = await stripe.tax.transactions.list({
  limit: 10,
  reference: 'order_12345'
});

Tax Settings

Tax.Settings

Manage global tax settings and configurations:

interface TaxSettings {
  object: 'tax.settings';
  defaults: {
    tax_behavior: 'inclusive' | 'exclusive';
    tax_code?: string;
  };
  head_office?: {
    address: {
      city?: string;
      country: string;
      line1?: string;
      line2?: string;
      postal_code?: string;
      state?: string;
    };
  };
  status: 'active' | 'pending';
  status_details: {
    active?: {
      status: 'active';
    };
    pending?: {
      status: 'pending';
      missing_fields: Array<string>;
    };
  };
}

// Retrieve tax settings
const settings = await stripe.tax.settings.retrieve();

// Update tax settings
const updated = await stripe.tax.settings.update({
  defaults: {
    tax_behavior: 'exclusive',
    tax_code: 'txcd_99999999'
  },
  head_office: {
    address: {
      line1: '354 Oyster Point Blvd',
      city: 'South San Francisco',
      state: 'CA',
      postal_code: '94080',
      country: 'US'
    }
  }
});

Tax Registrations

Tax.Registrations

Manage tax registrations for different jurisdictions:

interface TaxRegistration {
  id: string;
  object: 'tax.registration';
  active_from: number;
  country: string;
  country_options: {
    [key: string]: {
      standard_tax_id?: {
        type: string;
        value: string;
      };
      type: 'simplified' | 'standard';
    };
  };
  created: number;
  expires_at?: number;
  livemode: boolean;
  status: 'active' | 'expired' | 'scheduled';
}

// Create tax registration
const registration = await stripe.tax.registrations.create({
  country: 'US',
  country_options: {
    us: {
      type: 'state_tax_id',
      state: 'CA'
    }
  },
  active_from: Math.floor(Date.now() / 1000)
});

// Create EU registration
const euRegistration = await stripe.tax.registrations.create({
  country: 'IE',
  country_options: {
    ie: {
      type: 'oss_union',
      standard_tax_id: {
        type: 'eu_vat',
        value: 'IE1234567FA'
      }
    }
  },
  active_from: Math.floor(Date.now() / 1000)
});

// Retrieve registration
const retrievedReg = await stripe.tax.registrations.retrieve('taxreg_123');

// Update registration
const updatedReg = await stripe.tax.registrations.update('taxreg_123', {
  expires_at: Math.floor(Date.now() / 1000) + (365 * 24 * 60 * 60), // 1 year
  active_from: Math.floor(Date.now() / 1000)
});

// List registrations
const registrations = await stripe.tax.registrations.list({
  status: 'active'
});

Integration with Other Resources

Automatic Tax on Products

// Create product with tax code
const taxableProduct = await stripe.products.create({
  name: 'Digital Service',
  tax_code: 'txcd_10103001' // Digital services tax code
});

// Create price with tax behavior
const taxInclusivePrice = await stripe.prices.create({
  product: taxableProduct.id,
  unit_amount: 1200, // €12.00 including tax
  currency: 'eur',
  tax_behavior: 'inclusive'
});

PaymentIntents with Tax

// PaymentIntent with automatic tax
const paymentIntent = await stripe.paymentIntents.create({
  amount: 2000,
  currency: 'usd',
  customer: 'cus_123',
  automatic_tax: {
    enabled: true
  },
  metadata: {
    tax_calculation: 'taxcalc_123'
  }
});

Stripe Tax handles the complexity of global tax compliance, providing accurate real-time calculations, automated tax collection, and detailed reporting for tax authorities across multiple jurisdictions.

Install with Tessl CLI