Reference Data | Taxes | Set Taxes

Set Taxes

This endpoint creates new VAT/tax rates or updates existing ones through https://easycms.fi/public_api/set_taxes/.

Column naming note: on this platform the column vat_name carries the numeric rate (e.g. 24) and tax_desc carries the human-readable description in multiple languages. Existing products keep referencing the vatId — changing the rate of an ID changes it everywhere that ID is used.

Endpoint and Method

• Endpoint: https://easycms.fi/public_api/set_taxes/
• Method: POST
• Content-Type: application/json

Authentication

• Header: Authorization1: {API_TOKEN}
• Body parameters: username, password, account

Request Parameters

Creating a tax rate (omit vatId)

Parameter	Type	Required	Description
username	string	Yes	API username
password	string	Yes	API password
account	string	Yes	Account domain
vat_name	number	Yes	The VAT rate percentage (e.g. 24, 14, 0)
tax_desc	string | object	No	Description. A plain string is stored as en_GB; or pass a {lang: name} object. Defaults to "VAT <rate>%"
vatNumber	integer	No	Reference number. Defaults to MAX + 1
vat_code	string	No	VAT code string (e.g. MYK24)
vat_account	string	No	Ledger account reference
parent_id	integer	No	Parent tax ID (default 0)
visible	integer	No	1 = visible (default), 0 = hidden

Updating a tax rate (include vatId)

Parameter	Type	Required	Description
username	string	Yes	API username
password	string	Yes	API password
account	string	Yes	Account domain
vatId	integer	Yes	Tax ID to update
vat_name	number	No	New rate percentage
tax_desc	string | object	No	New description (string or {lang: name} object)
vatNumber	integer	No	New reference number
vat_code	string	No	VAT code string
vat_account	string	No	Ledger account reference
parent_id	integer	No	Parent tax ID
visible	integer	No	1 = visible, 0 = hidden

Only the fields you provide are updated. cr_tax_id / cr_tax_name are reserved for the cash-register sync and are ignored.

Behavior

• Create: validates the required fields, resolves vatNumber (MAX+1 when omitted), inserts the tax rate, and returns the new vatId.
• Update: validates that vatId exists, applies only the provided fields, and returns the refreshed row plus a changes summary (old → new per field).
• Rate changes propagate: invoices store vat_percent at the time of invoicing, but live pricing always uses the rate of the referenced vatId — update rates with care.
• Every tax insert/update writes to the account's activity log automatically.

Response Format

{
    "status": "success",
    "message": "Tax created successfully",
    "data": {
        "vatId": 10,
        "tax": {
            "vatId": "10",
            "cr_tax_id": null,
            "cr_tax_name": null,
            "tax_desc": "{\"en_GB\": \"VAT 13.5%\"}",
            "vat_name": "13.5",
            "vatNumber": "10",
            "visible": "1",
            "parent_id": "0",
            "vat_code": "",
            "vat_account": ""
        }
    },
    "changes": {
        "tax_created": {
            "vatId": 10,
            "vat_name": 13.5,
            "vatNumber": 10
        }
    }
}

Update responses carry message: "Tax updated successfully" and a changes.tax object with old/new values per updated field.

Error Responses

HTTP Code	Error Code	Description
400	MISSING_REQUIRED_FIELDS	vat_name (the rate) missing on create
400	NOTHING_TO_UPDATE	No valid tax fields provided on update
404	TAX_NOT_FOUND	vatId does not exist
500	CREATE_FAILED / UPDATE_FAILED	Database write failed

Call Examples

Create a VAT rate

curl -X POST "https://easycms.fi/public_api/set_taxes/" \
  -H "Content-Type: application/json" \
  -H "Authorization1: YOUR_API_TOKEN" \
  -d '{
    "username": "your_username",
    "password": "your_password",
    "account": "your_account",
    "vat_name": 13.5,
    "tax_desc": {"en_GB": "Reduced VAT 13.5%", "fi": "Vähennetty ALV 13,5 %"},
    "vat_code": "MYK135"
  }'

Update a rate

curl -X POST "https://easycms.fi/public_api/set_taxes/" \
  -H "Content-Type: application/json" \
  -H "Authorization1: YOUR_API_TOKEN" \
  -d '{
    "username": "your_username",
    "password": "your_password",
    "account": "your_account",
    "vatId": 10,
    "vat_name": 14
  }'