> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/admin/category-nodes/delete-a-category-node.md).

# Delete a category node

Deletes a category node together with its descendants. This is a **hard delete** — the rows are removed from the database.

The node's own menu item and pretty URL are deleted with it, and a redirect is kept from the deleted pretty URL to the node's `/category/{pk}/` route (which no longer resolves once the node is gone). The pretty URLs of deleted **descendants** are left in place and receive no redirect, so delete a branch node by node if their storefront URLs matter.

Deletion is refused with `406 Not Acceptable` in two cases:

| Error code       | Condition                                                             |
| ---------------- | --------------------------------------------------------------------- |
| `category_600_4` | The node is a tree root.                                              |
| `category_600_5` | The node or any of its descendants still has products filed under it. |

Detach the products through the `product_category` endpoints before deleting a branch. The wording of the error message is translated, so match on `error_code` rather than on the message text.

````json
{"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"tags":[{"name":"Category Nodes","description":"Administrative endpoints for **category nodes** — the nodes of the catalog category tree that products are filed under and that the storefront navigation, category pages, and category landing pages are built from.\n\nA category node carries a display name, a client-supplied `uuid`, its position in the tree (`depth` and `path`), an optional default sort option for its category page, and a free-form set of EAV attributes. The tree is stored as a *materialized path* structure: every node's `path` is the concatenation of a fixed-width step per tree level, so a node and its descendants are exactly the records whose `path` starts with that node's `path`.\n\nProducts are attached to categories through the `product_category` endpoints, the sort options referenced here are managed with `sort_options`, and the storefront-facing menu is kept in sync automatically — see **Side Effects of Writing a Category Node**.\n\n## Core Capabilities\n\n**1. Listing & Filtering**\n* Retrieve a paginated list of category nodes.\n* Filter by `id`, `uuid`, `name`, or `depth` — all exact matches.\n* Order results with the `sort` parameter, as described under **Filtering & Ordering**.\n\n**2. Full CRUD**\n* Create a node under an existing parent, or — subject to the restriction under **Creating a Tree Root** — as a new tree root.\n* Retrieve a single node.\n* Fully or partially update a node — including moving it, together with its whole subtree, to a different parent or a different position among its siblings.\n* Delete a node. Deletion is a **hard delete** and is refused for tree roots and for nodes that still hold products.\n\n## Category Node Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `pk` | integer | The unique identifier of the node. Assigned by the server; read-only. |\n| `name` | string (max 64 chars) | The display name of the node. The only field required on create and on full update. Translatable — see **Multilingual Names**. |\n| `uuid` | string (UUID) | A client-supplied unique identifier, used by integrations to address the node without knowing its `pk`. **Always send it on create** — see the warning under **Sending `uuid` on Create**. Must be unique across all category nodes. Optional on update. |\n| `depth` | integer | Read-only. The node's level in the tree, starting at `1` for a tree root. Assigned by the server from the node's position. |\n| `path` | string (max 255 chars) | Read-only. The node's materialized path — one step of exactly 4 characters per tree level (e.g. `0001` for a root, `00010002` for a child of it). Each step is a **base-36** number using the alphabet `0-9A-Z`, so the 10th sibling's step is `000A` and the 36th is `0010`: use `path` for prefix matching, but never parse a step as a decimal number. Assigned by the server; a `path` sent in a request body is ignored. |\n| `parent` | integer | **Write-only.** The identifier of the node to file this node under. See **Tree Structure & Positioning**. |\n| `prev_sibling` | integer | **Write-only.** The identifier of the sibling the node should be placed immediately after. See **Tree Structure & Positioning**. |\n| `absolute_url` | string | Read-only. The storefront path of the node's category page — its pretty URL when one exists (e.g. `/shoes/`), otherwise the default `/category/{pk}/` route. See **Pretty URLs**. |\n| `menuitemmodel` | string (UUID) or `null` | Read-only. The `uuid` of the menu item that mirrors this node in the storefront navigation, or `null` when the node has no menu item. |\n| `sort_option` | integer or `null` | The identifier of the sort option (`sort_options`) used as the default ordering of the node's category-page product listing. Applied only when the visitor has not chosen an explicit sort. Optional. **Ignored on create** — see **Fields Ignored on Create**. |\n| `attributes` | object | On **write**, the node's EAV attribute values keyed by attribute name; on **read**, the merged representation described under **Attributes**. Write-only in the field definition but always present in responses. **Ignored on create.** |\n| `attributes_kwargs` | object | **Write-only.** Supplementary metadata for the stored attributes (labels and similar), keyed by attribute name. **Ignored on create.** |\n| `localized_attributes` | object | **Write-only.** Attribute values and translated field values per language, keyed by language code. See **Multilingual Names**. |\n| `localized_attributes_kwargs` | object | **Write-only.** Per-language supplementary attribute metadata, keyed by language code. **Ignored on create.** |\n\n## Sending `uuid` on Create\n\n> **Important:** `uuid` is not enforced as a required field by the API, but the create service cannot run without it. Omitting `uuid` from a `POST /category_node/` body produces an **unhandled server error (HTTP 500)**, not a `400` validation error. Always generate and send a `uuid` on create. A `uuid` that is already in use *is* reported properly, as a `400` on the `uuid` field.\n\n## Creating a Tree Root\n\nA node created without `parent` becomes a new tree root, and the server also creates a **root menu item** for it in the storefront navigation. Only one visible root menu item may exist, so on any deployment that already has a storefront menu the attempt is rejected:\n\n`406 Not Acceptable` with `error_code: menu_item_200` (\"Root Menu Item already exist.\")\n\nThe node is rolled back and nothing is created. In practice, integrations create nodes **under an existing `parent`**; creating a root is a one-time bootstrapping operation. The same `406` can also surface when creating a child whose parent is a root with no menu item of its own, because the server then tries to create the missing root menu item first.\n\n## Tree Structure & Positioning\n\nWhere a node ends up is decided by `parent` and `prev_sibling`, both write-only:\n\n| Request | Result |\n|---------|--------|\n| Create with neither | The node becomes a new **tree root** (`depth` = `1`) — see **Creating a Tree Root**. |\n| Create with `parent` | The node becomes the **first child** of `parent`. |\n| Create with `parent` and `prev_sibling` | The node is placed immediately **after** `prev_sibling`. |\n| Create with `prev_sibling` but no `parent` | `prev_sibling` is **silently ignored** and the node becomes a new tree root. |\n| Update with neither | The node is re-positioned as the **first child of its current parent**. A tree root stays where it is. |\n| Update with `parent` | The node — **and its entire subtree** — is moved under `parent`, as its first child. |\n| Update with `prev_sibling` | The node is moved immediately **after** `prev_sibling`, adopting that sibling's parent. |\n| Update with `parent` **and** `prev_sibling` | `prev_sibling` **wins and `parent` is silently ignored.** The node moves after `prev_sibling`, under that sibling's parent — which may be a different branch than the `parent` you sent. |\n\n> **Important:** every update re-positions the node. Because `prev_sibling` defaults to nothing, a `PUT` or `PATCH` that only changes a node's `name` still moves that node to the front of its sibling list. Send `prev_sibling` whenever the node's position among its siblings must be preserved. (A tree root is exempt, because it has no parent to be re-ordered under.)\n\nAny move rewrites the `path` of the node and of every descendant, and therefore also their `depth`. `parent` and `prev_sibling` are never echoed back in the response; read the resulting position from `depth` and `path`.\n\n## Fields Ignored on Create\n\nThe create operation persists only `name`, `uuid`, the position given by `parent` / `prev_sibling`, and `localized_attributes`. `attributes`, `attributes_kwargs`, `localized_attributes_kwargs`, and `sort_option` are accepted and pass field validation but are **not stored**. Send them in a follow-up `PATCH /category_node/{id}/`, where all of them are honored.\n\n## Attributes\n\nRequests write `attributes` as a flat mapping of attribute name to value.\n\n> **Note:** these endpoints do **not** validate `attributes` against the schema registered for the category-node content type (managed with the `schema_types` and `content_types` endpoints). Values are stored verbatim — an unknown attribute name or a wrongly-typed value is accepted and persisted as sent. Validate on the client side if the schema matters to you.\n\nResponses return the **merged** representation instead of the value written: every attribute becomes an object pairing the value with its metadata, and multi-valued attributes become a list of such objects.\n\n```json\n{\n  \"attributes\": {\n    \"size_chart\": {\"value\": 12, \"kwargs\": {\"label\": \"Women's Shoes\"}},\n    \"badges\": [\n      {\"value\": \"new\", \"kwargs\": {\"label\": \"New Season\"}},\n      {\"value\": \"sale\", \"kwargs\": {\"label\": \"On Sale\"}}\n    ]\n  }\n}\n```\n\nThe merged object also folds in the entries of `localized_attributes` for the default language and for the language of the request. Because translated *field* values live there too, a node that has a translated name comes back with the internal `l_name` entry inside `attributes` alongside its real attributes — ignore keys beginning with `l_`.\n\n## Multilingual Names\n\n`name` is a translatable field. The value sent to these endpoints is stored on the node itself and is the value of the deployment's default language. Translations live in `localized_attributes`, keyed by language code, with the translated field name prefixed by `l_`:\n\n```json\n{\n  \"localized_attributes\": {\n    \"en\": {\"l_name\": \"Shoes\"},\n    \"de\": {\"l_name\": \"Schuhe\"}\n  }\n}\n```\n\nResponses render `name` (and the attribute values) in the language of the request, falling back to the default language when no translation exists. Which language that is depends on the `Accept-Language` header and on the `IGNORE_ACCEPT_LANGUAGE_HEADER` dynamic setting — see **Dynamic Settings & Environment Variables**.\n\n`localized_attributes` and `localized_attributes_kwargs` are write-only and are never echoed back, so the stored translations cannot be read back through these endpoints. Read a translated `name` by requesting the node in the language you want instead.\n\n## Pretty URLs\n\nCreating or updating a node regenerates its pretty URL from the node's name, and `absolute_url` reflects the result. Renaming a node therefore changes its storefront URL; the previous URL is kept as a redirect so existing links and search-engine results keep working. A generated path that collides with an existing one gets a numeric suffix (`/shoes-1/`); if a collision still remains when an *existing* pretty URL is being updated, the request is rejected with `406` and `pretty_url_100_1`.\n\nFailures are handled differently by the two write paths:\n\n| Operation | Behavior on a pretty-URL failure |\n|-----------|----------------------------------|\n| Create | Only a generated path that resolves to `/` (`pretty_url_100_6`) is logged and ignored — the node is still created, and `absolute_url` falls back to the default `/category/{pk}/` route. **Any other pretty-URL failure (`pretty_url_100_1`, `pretty_url_100_2`, `pretty_url_100_3`) is rejected with `406` and the node is not created.** |\n| Update | No failure is swallowed: the request is rejected with `406` and a `pretty_url_100_*` error code. **The re-positioning is not undone** — see the warning below. |\n\n> **Important:** on an update, the node is moved *before* the pretty URL is regenerated, and the move is not part of the rolled-back transaction. A `406` from an update therefore leaves the node **already moved** while its URL and other fields are unchanged. Re-read the node and retry rather than assuming the request had no effect.\n\nWhen the node has no pretty URL at all, `absolute_url` is the default `/category/{pk}/` route — rendered as `/{language}/category/{pk}/` on deployments that enable `I18N_ACTIVE`.\n\nWhether a pretty URL is generated per language, how the slug is built, and whether the default language's URL carries a language prefix are controlled by the settings listed under **Dynamic Settings & Environment Variables**. A `UrlGeneratorConfig` row registered for the category-node content type (managed with the `url_generator_configs` endpoints) **replaces the default URL template entirely** and is the strongest lever on the resulting `absolute_url`.\n\n## Side Effects of Writing a Category Node\n\n| Operation | Side effects |\n|-----------|--------------|\n| Create | A matching menu item is created in the storefront navigation (a root menu item for a tree root — see **Creating a Tree Root** — otherwise a child of the parent's menu item). A pretty URL is generated. |\n| Update | The pretty URL is regenerated, and a redirect from the old URL is kept. If the move changed the node's `path`, a background job re-indexes every active, listable product filed under the node's **new parent's** branch — which includes the node's new siblings and their descendants. Products under the node's previous location are **not** re-indexed. |\n| Delete | The node's own menu item and pretty URL are deleted, with a redirect kept from the deleted URL. Descendants are removed too, but their pretty URLs are **not** cleaned up — see **Deleting a Category Node**. |\n\n## Deleting a Category Node\n\n`DELETE /category_node/{id}/` removes the row — there is no soft delete — but it is refused in two cases, both answered with `406 Not Acceptable`:\n\n| Error code | Condition |\n|------------|-----------|\n| `category_600_4` | The node is a **tree root**. Roots cannot be deleted. |\n| `category_600_5` | The node **or any of its descendants** still has products filed under it. Detach the products through the `product_category` endpoints first. |\n\nDeleting a node deletes its descendants along with it, so a branch is removed by deleting its topmost node once every product has been detached.\n\n> **Note:** only the deleted node's *own* menu item and pretty URL are cleaned up. The pretty URLs of deleted descendants are left in place and receive no redirect, and the redirect kept for the deleted node points at its `/category/{pk}/` route, which no longer resolves. Delete a branch node by node if the descendants' storefront URLs matter to you.\n\n## Filtering & Ordering\n\nThe list endpoint accepts these filters, all **exact** matches:\n\n| Parameter | Match |\n|-----------|-------|\n| `id` | The node's identifier. |\n| `uuid` | The node's client-supplied UUID. |\n| `name` | The node's stored name, exactly and case-sensitively. There is no contains or case-insensitive variant. |\n| `depth` | The node's level in the tree — `?depth=1` returns the tree roots, `?depth=2` their direct children. |\n\nThere is no filter for `parent` or `path`, so a node's children are read by filtering on `depth` and matching `path` prefixes client-side, or through the storefront category endpoints.\n\nResults have no default ordering; the paginator falls back to ordering by `pk` ascending. Use the `sort` parameter to order on `pk`, `name`, `uuid`, `depth`, `path`, or `sort_option`; prefix a field with a hyphen for descending order (e.g. `?sort=-depth`). Ordering by `name` uses the stored default-language name, not the translated one.\n\n`absolute_url` and `menuitemmodel` are **not** sortable — they are computed rather than stored. An unrecognised `sort` value is silently ignored rather than rejected, so a typo produces unsorted results instead of an error.\n\n> **Note:** `?sort=get_absolute_url` — the internal name behind `absolute_url` — passes the server's sort validation but then fails at the database level and returns a server error. Sort only on the six fields listed above.\n\n## Dynamic Settings & Environment Variables\n\nThese endpoints are affected by the following dynamic settings, configured in the management panel. Each is referenced again in the description of the operations it affects.\n\n| Key | Type | Default | Effect |\n|-----|------|---------|--------|\n| `IGNORE_ACCEPT_LANGUAGE_HEADER` | boolean | `true` | Whether the `Accept-Language` header is discarded before the request is processed. Affects **every** operation: the language it selects is the language `name` and the merged `attributes` are rendered in, and it is also the language a business-error message is translated into. While it is `true` (the default), the header is honored only when the request also carries an `X-Omnitron-Session` header; otherwise the deployment's default language is used. Registered in `omnishop/api/settings/conf.py`. |\n| `PRETTY_URL_INCLUDE_DEFAULT_LANGUAGE` | boolean | `false` (falls back to the Django setting of the same name) | Whether the pretty URL generated for the site language carries a language prefix. Affects **create** (`POST /category_node/`) and **update** (`PUT` / `PATCH`), because both regenerate the node's pretty URL, and therefore changes the `absolute_url` returned in the response. Registered in `omnishop/prettyurls/settings/conf.py`. |\n\nNo other dynamic setting is read on the request path of these endpoints. In particular, the two settings registered in `omnishop/catalogs/settings/conf.py` — `GROUPED_PRODUCT_PRICE_SELECTOR` and `LIST_SIMPLE_INSTEAD_OF_META` — govern product pricing and product listability and are **not** read here. `SWAP_PRETTY_URLS_FOR_NOT_LISTABLE_PRODUCTS` and `FORCE_NOT_REDIRECT_FOR_I18N`, registered alongside `PRETTY_URL_INCLUDE_DEFAULT_LANGUAGE`, apply to product URLs and to storefront redirect handling respectively, and `CATEGORY_DETAIL_MAX_DEPTH` is read by the storefront category page rather than by these administrative endpoints.\n\n**Deployment settings.** The pretty-URL generation these endpoints trigger also reads the following Django settings. They are part of the deployment configuration — supplied through environment variables of the same names — rather than the management panel, so they cannot be changed at runtime:\n\n| Setting | Default | Effect |\n|---------|---------|--------|\n| `LANGUAGE_CODE` | deployment-specific | The default language. `name` sent to these endpoints is stored as this language's value; other languages are read from and written to `localized_attributes`. |\n| `LANGUAGES` | deployment-specific | The configured languages. Together with `PRETTY_URL_MULTI_LANGUAGE` this decides which per-language pretty URLs a node has — see the note below. |\n| `PRETTY_URL_MULTI_LANGUAGE` | `false` | When `true`, create and update generate one pretty URL per configured language instead of only the default-language one. |\n| `PRETTY_URL_SITE_LANGUAGE_CODE` | `LANGUAGE_CODE` | Which language counts as the site language when deciding whether a generated pretty URL needs a language prefix; works together with `PRETTY_URL_INCLUDE_DEFAULT_LANGUAGE`. |\n| `PRETTY_URL_FORCE_UNICODE_SLUG` | `false` | Whether the slug built from the node's name keeps Unicode characters instead of being transliterated. Changes the generated `absolute_url`. |\n| `PRETTY_URL_ONLY_ASCII` | `false` | Whether the generated slug is restricted to ASCII. Changes the generated `absolute_url`. |\n| `I18N_ACTIVE` | `false` | When `true`, storefront routes are language-prefixed, so a node with no pretty URL reports `absolute_url` as `/{language}/category/{pk}/` instead of `/category/{pk}/`. |\n\n> **Note on per-language pretty URLs:** while `PRETTY_URL_MULTI_LANGUAGE` is off (the default), every create and update **removes** the node's per-language pretty URLs for all non-default configured languages, leaving only the default-language one. While it is on, a language whose generated path duplicates one already produced in the same run has its per-language pretty URL removed. A language that is dropped from `LANGUAGES` is never visited, so a pretty URL it already owns is left behind."}],"servers":[{"description":"Omnitron Remote Proxy (external access — recommended)","url":"https://{omnitron_url}/api/v1/remote/{channel_id}","variables":{"omnitron_url":{"default":"sandbox.akinon.com","description":"Omnitron server URL (e.g., {omnitron.akinon.com})"},"channel_id":{"default":"1","description":"The channel identifier the remote request is routed through"}}},{"description":"Commerce API Server (internal / direct access only)","url":"https://{commerce_url}/api/v1","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Internal commerce server URL, reachable only from within the Omnitron network"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token credential sent in the Authorization header, in the form: `Token <your-token>`. Requires a staff (admin) account."}},"responses":{"Unauthorized":{"description":"Authentication credentials were not provided or are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The authenticated user does not have administrator privileges.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"CategoryNodeNotFound":{"description":"No category node exists with the given identifier.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"CategoryNodeBusinessError":{"description":"The request is well-formed but violates a business rule — creating a tree root when the storefront navigation already has a root menu item, deleting a tree root or a node that still holds products, or a pretty URL that could not be generated. See the `CategoryNodeBusinessError` schema for the individual codes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryNodeBusinessError"}}}}},"schemas":{"Error":{"type":"object","description":"An error response.","properties":{"detail":{"type":"string","description":"A human-readable description of the error."}},"additionalProperties":true},"CategoryNodeBusinessError":{"type":"object","description":"Returned when a category node request is valid in form but violates a business rule.\n\nCodes raised by these endpoints:\n* `menu_item_200` — a tree root was created (`parent` omitted) while the storefront navigation already has a visible root menu item. Nothing is created.\n* `category_600_4` — the node targeted for deletion is a tree root.\n* `category_600_5` — the node targeted for deletion, or one of its descendants, still has products filed under it.\n* `pretty_url_100_1` — the pretty URL generated for the node is already taken by another record.\n* `pretty_url_100_2` — the storefront route the pretty URL is built for could not be resolved.\n* `pretty_url_100_3` — the view behind the resolved route could not be found.\n* `pretty_url_100_6` — the generated pretty URL resolved to `/`, which is not a valid path. On create this one is logged and ignored instead of returned.\n\nOn create, a `pretty_url_*` failure means the node was **not** created. On update it means the node was already re-positioned before the failure and that move was not rolled back.\n\nThe message is translated, so match on `error_code` rather than on the message text.","properties":{"non_field_errors":{"type":"string","description":"A human-readable message describing the business rule that was violated."},"error_code":{"type":"string","description":"A stable code identifying the specific business rule violation."}},"additionalProperties":true}}},"paths":{"/category_node/{id}/":{"delete":{"tags":["Category Nodes"],"operationId":"deleteCategoryNode","summary":"Delete a category node","description":"Deletes a category node together with its descendants. This is a **hard delete** — the rows are removed from the database.\n\nThe node's own menu item and pretty URL are deleted with it, and a redirect is kept from the deleted pretty URL to the node's `/category/{pk}/` route (which no longer resolves once the node is gone). The pretty URLs of deleted **descendants** are left in place and receive no redirect, so delete a branch node by node if their storefront URLs matter.\n\nDeletion is refused with `406 Not Acceptable` in two cases:\n\n| Error code | Condition |\n|------------|-----------|\n| `category_600_4` | The node is a tree root. |\n| `category_600_5` | The node or any of its descendants still has products filed under it. |\n\nDetach the products through the `product_category` endpoints before deleting a branch. The wording of the error message is translated, so match on `error_code` rather than on the message text.","responses":{"204":{"description":"The category node was deleted successfully. No response body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/CategoryNodeNotFound"},"406":{"$ref":"#/components/responses/CategoryNodeBusinessError"}}}}}}
````


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://apidocs.akinon.com/commerce-openapis/admin/category-nodes/delete-a-category-node.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
