Replace the organization's tax settings with the whole configuration sent

PUT /settings/tax

The country must be the region's (AU for AU-GST, NZ for NZ-GST, GB for UK-VAT, a member state for EU-VAT); rates are { class, rateBps, from } rows — the rate in force on a sale's tax point is the row with the latest from on or before it — and zero-rated, exempt and out-of-scope carry no rate but 0. Appends inventory.tax-settings-configured. Idempotent by content: the event is a last-write-wins snapshot of the whole configuration, and a body equal to the settings in force appends nothing. A rate change applies to documents priced after it; an issued document keeps the rate it was priced at. A financialYearStart that would leave a scheduled change of accounting basis off the first day of a financial year is 409 BasisChangeRefused (not-a-year-start, with the new year's changeDays): move or take back the change first. timeZone (an IANA name) is where the books keep their days: an accounting period ends at midnight there, and the ledger apps' journals are dated by its days.

Access

Requires settings:write.

How scopes come from roles: Scopes and roles. Getting a token: Authentication and app tokens.

Retries

Idempotent by content: the event is a last-write-wins snapshot of the whole configuration, and a body equal to the settings in force appends nothing.

Why every write carries a key: Idempotency and retries.

Facts appended

inventory.tax-settings-configured

What a fact is: Facts and the journal.

AI agent tool

No agent tool. Tax registration and rates decide what every customer is charged: the owner's call in Settings › Tax, where the region's rates are prefilled.

Connecting an agent: AI agents.

Example

curl

curl -X PUT 'https://inventory.getmanifold.io/settings/tax' \
  -H "Authorization: Bearer $MANIFOLD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "region": "AU-GST",
  "country": "AU",
  "taxNumber": "12 345 678 901",
  "rates": [
    {
      "class": "standard",
      "rateBps": 1000,
      "from": "2000-07-01"
    },
    {
      "class": "zero-rated",
      "rateBps": 0,
      "from": "2000-07-01"
    }
  ],
  "financialYearStart": 7,
  "timeZone": "Australia/Sydney",
  "defaultConvention": "inclusive",
  "chargeClass": "follows-goods"
}'

JavaScript (fetch)

const response = await fetch("https://inventory.getmanifold.io/settings/tax", {
  method: "PUT",
  headers: { Authorization: `Bearer ${process.env.MANIFOLD_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "region": "AU-GST",
    "country": "AU",
    "taxNumber": "12 345 678 901",
    "rates": [
      {
        "class": "standard",
        "rateBps": 1000,
        "from": "2000-07-01"
      },
      {
        "class": "zero-rated",
        "rateBps": 0,
        "from": "2000-07-01"
      }
    ],
    "financialYearStart": 7,
    "timeZone": "Australia/Sydney",
    "defaultConvention": "inclusive",
    "chargeClass": "follows-goods"
  }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const answer = await response.json();

Request body · application/json

{
  "region": "AU-GST",
  "country": "AU",
  "taxNumber": "12 345 678 901",
  "rates": [
    {
      "class": "standard",
      "rateBps": 1000,
      "from": "2000-07-01"
    },
    {
      "class": "zero-rated",
      "rateBps": 0,
      "from": "2000-07-01"
    }
  ],
  "financialYearStart": 7,
  "timeZone": "Australia/Sydney",
  "defaultConvention": "inclusive",
  "chargeClass": "follows-goods"
}

Response · 200 · application/json

{
  "region": "AU-GST",
  "country": "AU",
  "taxNumber": "12 345 678 901",
  "rates": [
    {
      "class": "standard",
      "rateBps": 1000,
      "from": "2000-07-01"
    },
    {
      "class": "zero-rated",
      "rateBps": 0,
      "from": "2000-07-01"
    }
  ],
  "financialYearStart": 7,
  "timeZone": "Australia/Sydney",
  "defaultConvention": "inclusive",
  "chargeClass": "follows-goods"
}

The panel writes this call in other languages. It does not send it: Manifold's APIs do not take calls from a web page on another site, so run the call from your own code or terminal. The whole API as OpenAPI: inventory-manager.openapi.json. Base URL https://inventory.getmanifold.io.

Errors

Every refusal is a status and a JSON body whose _tag names it. A refused call changes nothing.

`401`

Refusal	What it means	What to do
`Unauthorized` reason	The token is missing, expired or not one Manifold issued.	Get a fresh token and send the call again.
`TokenAlreadyUsed` tokenId	A single-use app token was already spent.	Mint a new token for this call.

`402`

Refusal	What it means	What to do
`SubscriptionRequired` status	The organization's subscription has lapsed, so writes are refused.	An owner settles billing. Reads still work meanwhile.

`403`

Refusal	What it means	What to do
`TenantRequired` userId	The token names no organization.	Choose the organization, then get a new token.
`ScopeRequired` required	The token's roles do not grant the scope this call needs.	Ask an owner or admin for a role that grants it.

`409`

Refusal	What it means	What to do
`BasisChangeRefused` problem, changeDays, changeableFrom	The accounting basis cannot change now. `changeableFrom` says when it can.	Make the change on or after that day.
`MirroredFromSource` source	This area is fed by your source system until the organization goes live.	Make the change in the source system, or go live first.

`503`

Refusal	What it means	What to do
`RequestLogUnavailable` tokenId, reason	The service could not record the request, so it did nothing.	Send the same request again shortly.

How refusals work everywhere: Errors.