Stripe.Tax reference

RetrieveTaxRate

Source: src/Stripe/RetrieveTaxRate.ts

Retrieve a bound Stripe Tax Rate over HTTP.

RetrieveTaxRate: Reading a Tax Rate

const retrieve = yield* Stripe.RetrieveTaxRate(vat);
const live = yield* retrieve();

RetrieveTaxRateHttp

Source: src/Stripe/RetrieveTaxRateHttp.ts Kind: Layer · Provides: Stripe.RetrieveTaxRate

HTTP implementation of RetrieveTaxRate. Provide it on the Function or Worker Effect.

RetrieveTaxRegistration

Source: src/Stripe/RetrieveTaxRegistration.ts

Retrieve a bound Stripe Tax Registration over HTTP.

RetrieveTaxRegistration: Reading a Tax Registration

const retrieve = yield* Stripe.RetrieveTaxRegistration(registration);
const live = yield* retrieve();

RetrieveTaxRegistrationHttp

Source: src/Stripe/RetrieveTaxRegistrationHttp.ts Kind: Layer · Provides: Stripe.RetrieveTaxRegistration

HTTP implementation of RetrieveTaxRegistration. Provide it on the Function or Worker Effect.

RetrieveTaxSettings

Source: src/Stripe/RetrieveTaxSettings.ts

Retrieve bound Stripe Tax Settings over HTTP. Tax Settings is an account singleton — the retrieve op has no id field; the bound resource associates the API key with the host.

RetrieveTaxSettings: Reading Tax Settings

const retrieve = yield* Stripe.RetrieveTaxSettings(settings);
const live = yield* retrieve();

RetrieveTaxSettingsHttp

Source: src/Stripe/RetrieveTaxSettingsHttp.ts Kind: Layer · Provides: Stripe.RetrieveTaxSettings

HTTP implementation of RetrieveTaxSettings. Provide it on the Function or Worker Effect. Tax Settings has no Stripe id — only the API key is bound.

TaxRate

Source: src/Stripe/TaxRate.ts

A Stripe Tax Rate — a percent tax applied to invoices, subscriptions, and Checkout Sessions. percentage and inclusive are immutable and changing them replaces the tax rate. Display name, active, description, jurisdiction fields, and metadata update in place.

Stripe does not hard-delete tax rates; destroying this resource deactivates it (active: false).

TaxRate: Creating a Tax Rate

Exclusive sales tax

const vat = yield* Stripe.TaxRate("vat", {
  displayName: "VAT",
  percentage: 20,
  inclusive: false,
});

Inclusive tax with metadata

const gst = yield* Stripe.TaxRate("gst", {
  displayName: "GST",
  percentage: 10,
  inclusive: true,
  taxType: "gst",
  metadata: { region: "au" },
});

TaxRate: Updating a Tax Rate

const vat = yield* Stripe.TaxRate("vat", {
  displayName: "VAT (paused)",
  percentage: 20,
  inclusive: false,
  active: false,
  metadata: { region: "eu" },
});

TaxRate: Deactivating a Tax Rate

// stack.destroy() / resource removal sets active: false
const vat = yield* Stripe.TaxRate("vat", {
  displayName: "VAT",
  percentage: 20,
  inclusive: false,
});

TaxRegistration

Source: src/Stripe/TaxRegistration.ts

A Stripe Tax Registration — records that your business is registered to collect tax in a region so Stripe Tax can calculate and collect it. Stripe does not register with tax authorities on your behalf.

country and countryOptions are immutable and changing them replaces the registration. activeFrom and expiresAt update in place.

A registration cannot be hard-deleted. Destroying this resource expires it (expiresAt: "now"). Expiration is permanent; to collect tax in that location again, create a new registration.

Tax registrations have no metadata field. Identity is the Stripe id (and, when the id is missing, a matching non-expired country + options pair). list() returns every non-expired registration on the account.

A head office address must be configured on Tax Settings before a registration can be created.

TaxRegistration: Creating a Tax Registration

US state sales tax

const california = yield* Stripe.TaxRegistration("ca-sales-tax", {
  country: "US",
  countryOptions: {
    us: { type: "state_sales_tax", state: "CA" },
  },
});

Simplified registration

const tajikistan = yield* Stripe.TaxRegistration("tj", {
  country: "TJ",
  countryOptions: { tj: { type: "simplified" } },
});

EU OSS Union

const irelandOss = yield* Stripe.TaxRegistration("ie-oss", {
  country: "IE",
  countryOptions: { ie: { type: "oss_union" } },
  activeFrom: "now",
});

TaxRegistration: Updating a Tax Registration

const california = yield* Stripe.TaxRegistration("ca-sales-tax", {
  country: "US",
  countryOptions: {
    us: { type: "state_sales_tax", state: "CA" },
  },
  expiresAt: 1893456000,
});

TaxRegistration: Expiring a Tax Registration

// stack.destroy() / resource removal sets expiresAt to "now"
const california = yield* Stripe.TaxRegistration("ca-sales-tax", {
  country: "US",
  countryOptions: {
    us: { type: "state_sales_tax", state: "CA" },
  },
});

TaxSettings

Source: src/Stripe/TaxSettings.ts

Account-level Stripe Tax Settings — default tax behavior, default tax code, and head-office address used by Stripe Tax calculations.

This is an account singleton: GET /v1/tax/settings always returns the merchant’s settings, and POST /v1/tax/settings updates them in place. There is no create or hard-delete. The first reconcile captures the pre-management snapshot (initialSettings); destroy posts that snapshot back. Stripe will not unset a field once it has been set, so a null original is left as-is on restore.

The Tax Settings object has no metadata. Alchemy does not stamp ownership keys.

TaxSettings: Configuring defaults

Exclusive default tax behavior

const settings = yield* Stripe.TaxSettings("tax", {
  defaults: { taxBehavior: "exclusive" },
});

Default tax code

const settings = yield* Stripe.TaxSettings("tax", {
  defaults: {
    taxBehavior: "exclusive",
    taxCode: "txcd_99999999",
  },
});

TaxSettings: Head office

const settings = yield* Stripe.TaxSettings("tax", {
  headOffice: {
    address: { country: "US", state: "CA" },
  },
});

TaxSettings: Restoring on destroy

// stack.destroy() posts `initialSettings` back (fields Stripe allows)
const settings = yield* Stripe.TaxSettings("tax", {
  defaults: { taxBehavior: "inclusive" },
});

UpdateTaxSettings

Source: src/Stripe/UpdateTaxSettings.ts

Update bound Stripe Tax Settings over HTTP. Tax Settings is an account singleton — the update op has no id field; the bound resource associates the API key with the host. Fields Stripe has already set cannot be removed.

UpdateTaxSettings: Updating Tax Settings

const update = yield* Stripe.UpdateTaxSettings(settings);
const live = yield* update({
  defaults: { tax_behavior: "exclusive" },
});

UpdateTaxSettingsHttp

Source: src/Stripe/UpdateTaxSettingsHttp.ts Kind: Layer · Provides: Stripe.UpdateTaxSettings

HTTP implementation of UpdateTaxSettings. Provide it on the Function or Worker Effect. Tax Settings has no Stripe id — only the API key is bound.