PUT
Edit a category
Company space For: Manager · Permission: categories.update Conditions
  • When is_taxable or vat_rate_id is sent, the caller also needs the category_taxes.update permission. tax_ids is not accepted here and is ignored; additional taxes are set with the category taxes action.
  • The handle must stay unique within the organization (the category’s own handle does not conflict).
  • On update every field is optional; omitted fields keep their stored value.
  • A tax change is refused when it would make a stored price of an item of this category impossible to calculate that could be calculated before.
  • The vat_rate_id rule is the same as on creation.
What else happens
  • When an image is sent it replaces the previous one; the previous file is deleted after the change is committed.
  • A change of is_taxable or vat_rate_id rewrites the category’s tax configuration for the current fiscal profile, which changes how items inheriting from the category are taxed; the list of additional taxes is left as it is.
Part of Organize with options and categories.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

category
string
required

Identifier of the category (27-character KSUID string).

Query Parameters

response
enum<string>
default:none

Response mode. Default none; none answers 204 No Content.

Available options:
none,
resource
fields
string

Comma-separated JSON keys of the root resource (id is always rendered). Available: vat_rate_id, is_taxable, id, handle, title, image_url, sort_order, created_at, updated_at, organization_id.

include
string

Comma-separated include paths, each optionally followed by its fields in parentheses: units(id,sku),units.uomUnit(id,name). Max depth 6, max 40 paths. Available: vat_rate, taxes.

Response

Resource (only with response=resource).

id

Identifier of the category (27-character KSUID string).

handle

URL-friendly identifier of the category, unique within the organization. Generated from the title (with a numeric suffix on conflict) when not sent at creation.

title

Display name of the category.

image_url

Public URL of the category image; null when the category has no image.

sort_order
integer

Display position of the category; lower values come first.

created_at

Date and time the record was created (ISO 8601, UTC).

updated_at

Date and time the record was last changed (ISO 8601, UTC).

organization_id

Identifier of the organization the record belongs to.

vat_rate_id

Identifier of the VAT rate set on the category for the company's current fiscal profile; null when none is set or no configuration exists.

vat_rate
object | null

VAT rate object (id, country_code, fiscal_status, name, code, rate, treatment, is_default, is_active). Only returned when selected with ?include=vat_rate.

taxes
array

Additional taxes applied to items of this category, in the order they are applied. Only returned when selected with ?include=taxes.

is_taxable
boolean | null

Whether items of this category are taxed in the company's current fiscal profile. null when no tax configuration exists yet for that profile (items are then treated as untaxed and unconfigured).