Tax Rates

Tax rates let you define reusable tax configurations that can be applied to invoices, payment links, and product plans. Tax is calculated and displayed to the customer at checkout.

Create a tax rate

POST/tax-rates

Request body

Parameter	Type	Required	Description
`displayName`	`string`	Yes	Display name (1–100 chars, e.g. "VAT")
`percentage`	`number`	Yes	Tax percentage (0–100)
`inclusive`	`boolean`	No	Whether tax is included in the price
`jurisdiction`	`string`	No	Tax jurisdiction (max 50, e.g. "US-CA")
`description`	`string`	No	Description (max 500)

SDK exampletypescript

const taxRate = await noderails.taxRates.create({
  displayName: 'Sales Tax',
  percentage: 8.25,
  inclusive: false,
  jurisdiction: 'US-TX',
  description: 'Texas state sales tax',
});

console.log(taxRate.id); // "tax_abc123"

cURLbash

curl -X POST https://api.noderails.com/tax-rates \
  -H "x-api-key: nr_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Sales Tax",
    "percentage": 8.25,
    "inclusive": false,
    "jurisdiction": "US-TX"
  }'

List tax rates

GET/tax-rates

Query parameters

Parameter	Type	Description
`includeInactive`	`"true" \| "false"`	Include archived/inactive tax rates

SDK exampletypescript

const taxRates = await noderails.taxRates.list();

for (const rate of taxRates) {
  console.log(rate.displayName, rate.percentage + '%');
}

Retrieve a tax rate

GET/tax-rates/:id

SDK exampletypescript

const rate = await noderails.taxRates.retrieve('tax_abc123');
console.log(rate.displayName); // "Sales Tax"
console.log(rate.percentage);  // 8.25

Update a tax rate

PUT/tax-rates/:id

Parameter	Type	Required	Description
`displayName`	`string`	No	Updated display name
`percentage`	`number`	No	Updated percentage
`inclusive`	`boolean`	No	Updated inclusive flag
`jurisdiction`	`string`	No	Updated jurisdiction
`description`	`string`	No	Updated description
`isActive`	`boolean`	No	Active/archived

SDK exampletypescript

const updated = await noderails.taxRates.update('tax_abc123', {
  percentage: 8.5,
  description: 'Updated Texas sales tax',
});

Archive a tax rate

DELETE/tax-rates/:id

Archives a tax rate (soft delete). Returns 204 No Content.

SDK exampletypescript

await noderails.taxRates.del('tax_abc123');

Response object

All responses are wrapped in { "success": true, "data": ... }. The list endpoint returns a flat array (not paginated). Delete returns 204 No Content.

TaxRate objectjson

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "merchantId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "displayName": "Sales Tax",
    "percentage": 8.25,
    "inclusive": false,
    "jurisdiction": "US-TX",
    "description": "Texas state sales tax",
    "isActive": true,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  }
}

TaxRate fields

idstringUnique tax rate UUID

merchantIdstringMerchant this tax rate belongs to

displayNamestringDisplay name (e.g. 'VAT', 'Sales Tax')

percentagenumberTax percentage (0–100)

inclusivebooleanWhether tax is included in the price

jurisdictionstring | nullTax jurisdiction (e.g. 'US-CA')

descriptionstring | nullAdditional description

isActivebooleanWhether the tax rate is active

createdAtstringISO 8601 creation timestamp

updatedAtstringISO 8601 last-update timestamp