Skip to main content
Tax rules change. A calculation you ran last quarter will not necessarily reproduce today, because the country’s ruleset has moved on. Pinning lets you name the exact ruleset a calculation should use, so a figure you showed a customer, filed, or stored can be recomputed and audited later. By default every calculation uses the current ruleset. That is the right choice for new work — pin only when you need a result to stay stable.

​
Find a version to pin

Ask which rulesets a country has: Response:
isLatest marks the ruleset a request uses when you do not pin. pinnable tells you whether a version can be requested by name.
Only pin a version with pinnable: true. Rulesets published before versioning was introduced cannot be reproduced — the rules they depended on were never captured — so requesting one returns a 400 rather than a result computed from the wrong rules.

​
Pin a calculation

Pass version alongside your usual request body: The same field works on Estimate Gross or Net Salary and Validate Tax Fields, and as a version query parameter on List Required Additional Tax Fields by Country. A pinned response echoes the version it used:
rulesetVersion appears only when you pin. Its absence means the current ruleset was used.

​
Pin the fields too

The inputs a country requires change between versions, so a stored payload can stop matching the ruleset it was collected for. Pass the same version to the fields endpoint to see the inputs as they were: The response carries version, effectiveFrom and pinnable alongside the field list, so you can record which contract a stored payload was built against.

​
When a pin is rejected

Pinning never falls back to current rules — a request that cannot be honoured fails instead of quietly returning a different answer. Each case returns a 400:
Read pinnable from the versions response before pinning and you will avoid the first three entirely.

​
Staying current

Pinning holds a calculation still; it does not keep you up to date. To see what changed since the version you are on, and whether the required fields moved: actionRequired tells you whether the tax field requirements changed, which is the case that needs code on your side rather than just a version bump.

​
Next Steps

Get Started

Run your first tax calculation

Tax API Reference

Full endpoint reference