Manage cost categories

A cost category is a label you attach to the individual cost lines that make up a product's landed cost — Freight, Customs Duty, Insurance, Handling, and more. When a landed-cost invoice is captured, each extracted line is assigned a cost category; that category drives how the cost is grouped in FIFO cost breakdowns and which nominal account it posts to. This page walks every task — creating, editing, archiving, merging, and deleting categories, plus managing the keyword aliases that let SKU auto-classify invoice lines — and calls out the guards that trip people up, especially system categories and the in-use delete guard.

Before you begin

• Cost categories are managed under Settings → Financials → Cost Categories. From the Financials settings page, open Cost Categories; the header's Keyword Aliases button takes you to the aliases screen.
• Keyword aliases are read and written through the landed-cost (purchasing) surface, so managing them requires read-write access to Purchase Orders. Everything else lives under Financials settings.
• Cost categories are account-wide — they're not per-warehouse or per-supplier. A rename or merge changes the category everywhere it's used.

Read the cost categories list

The Cost Categories table lists every category, active and archived, system and user-defined. It's loaded in full and filtered in the browser (there is no server-side pagination on this screen), so search and filters apply instantly across the whole set.

• Search matches on the category name (case-insensitive).
• Status filter: All, Active, or Archived.
• Type filter: All, User-defined, or System.
• Columns: Name, Type (System / User), Default Nominal Code, Status (Active / Archived), Usage, Created At, Updated At. Use the column selector to show or hide optional columns.

A lock icon next to a name marks a system category — its Edit, Archive, Merge, and Delete actions are disabled. User-defined rows are clickable and open the edit dialog.

This settings screen shows every category. Elsewhere in the app, category pickers (for example, when you assign a category to a landed-cost bill line) request the list in selectable mode, which excludes system categories — so Base Product and the decoration categories never appear as manual choices even though they're listed here.

Usage counts

The Usage column shows how many records point at each category. Hover the total for the breakdown across the three relations:

Count	What it tracks
financial_line_types	Financial line types mapped to this category (see product accounting)
bill_lines	Landed-cost / bill lines assigned to this category
breakdown_items	Sales-order FIFO cost-breakdown items tagged with this category
total	The sum of the three — the number that governs whether the category is deletable

Usage counts are only present when the list is loaded with counts requested (the Cost Categories screen always does this) or when you open a single category. A category with a total of 0 is truly unused and safe to delete; anything above 0 is in use.

Create a cost category

1. Go to Settings → Financials → Cost Categories (or press C on the list).
2. Click Create Cost Category.
3. Enter a Name.
4. Optionally pick a Default Nominal Code — the account landed-cost bill lines assigned to this category post to. Leave it blank to fall back to your nominal code mappings.
5. Click Create.

The name is required, capped at 255 characters, and must be unique across all categories (case-sensitive at the database level, but see the duplicate guards below). If the name already exists you get "A cost category with this name already exists."

New categories are always created as active and user-defined (never system) regardless of anything else you send.

"Did you mean?" duplicate suggestion

As you leave the Name field on a new category, SKU runs a fuzzy check and, if your name is within a small edit distance of an existing one, shows a "Did you mean <name>?" banner with a Use existing button. This steers you away from near-duplicates like Frieght vs Freight or Customs Duties vs Customs Duty. The match is case-insensitive, returns the closest existing name within a Levenshtein distance of 2 or less (one or two typo'd characters), and returns nothing if no name is that close — so for a genuinely new category no banner appears. Click Use existing to reuse the matched category instead of creating a new one, or ignore the banner and create your category anyway.

Edit a cost category

1. In the list, click a user-defined category's name (or its Edit pencil).
2. Change the Name and/or Default Nominal Code.
3. Click Update.

Renames follow the same rules as create — required, max 255, unique — except the uniqueness check ignores the category's own current name, so re-saving without changing the name never trips the duplicate error.

Renames don't rewrite history

A cost category is a Type 1 label: renaming it changes the name everywhere it appears going forward, but it does not rewrite historical FIFO cost breakdowns that were already snapshotted under the old name. Past sales-order COGS breakdowns keep the value they were costed at; only the display name updates on live references. If you need a genuinely different bucket, merge instead.

System categories can't be edited — the dialog shows an info banner and both the Name field and Update button are disabled for them.

Archive and unarchive a cost category

Archiving hides a category from the default (Active) view without deleting it or touching the records that reference it. It's a soft state change (Active → Archived).

To archive:

1. In the list, click the Archive action on a user-defined row and confirm.

To unarchive:

1. Set the Status filter to Archived (or All), find the category, click Unarchive, and confirm.

Key behaviors:

• References are untouched. Archiving doesn't detach the category from any bill line, breakdown item, or financial line type — it only hides the category from pickers and default views.
• Unarchive is blocked by a name collision. If, while a category was archived, someone created a different active category with the same (case-insensitive) name, unarchiving is rejected with "An active cost category named <name> already exists. Merge or rename before unarchiving." Rename one of them, or merge the active duplicate into the one you're restoring, then try again.
• System categories can't be archived.

Merge a cost category into another

Merging folds a source category into a target: every reference is re-pointed to the target, then the source is deleted. Use it to collapse duplicates (Freight + Shipping) or retire a category that's still in use.

1. In the list, click the Merge action on the source (user-defined) category.
2. In Merge Cost Category, pick a Target Category from the dropdown (active categories only; the source is excluded).
3. Click Merge.

What happens, in one locked database transaction:

• All bill lines, financial line types, and breakdown items on the source are re-pointed to the target.
• The source category is deleted.

Guards and edge cases:

• You can't merge a category into itself — "Cannot merge a cost category into itself."
• System categories can't be the source of a merge.
• History isn't rewritten. As with renames, merging re-points live references but doesn't rewrite already-snapshotted FIFO cost breakdowns — those keep their original category on historical layers.
• This can't be undone. Because the source is deleted at the end, there is no unmerge. The dialog warns you before you confirm.

Merge instead of force-delete

Merge is the safe way to remove a category that's still in use: it moves the references somewhere valid first, so nothing is left pointing at a deleted category. Reach for force-delete only when you're certain the category has no references you care about.

Delete a cost category

Deleting permanently removes a category. There are two layers of protection.

1. In the list, click the Delete action on a user-defined row.
2. If the category is referenced, the confirmation warns you (with the reference count) that merging is usually safer.
3. Confirm to delete.

How the guards work:

• Standard delete is blocked while in use. If the category's total usage (bill lines + breakdown items + financial line types) is greater than 0, the delete is rejected with "This cost category is still in use (N references). Archive or merge it first."
• ?force=true skips only the pre-check. A force-delete tells the manager to skip counting usage first — but it doesn't override the underlying guard. The model layer independently re-counts references on delete and, if any remain, still rejects with "This cost category is referenced by N record(s) and cannot be deleted. Archive or merge it first." In other words, force can never orphan a reference: a category with live references can't be hard-deleted by any path. To actually remove an in-use category, merge it (which re-points the references) or archive it.
• System categories are never deletable — "System cost categories cannot be deleted."
• A clean delete is permanent and can't be undone.

System (protected) categories

Some categories are seeded by SKU and flagged System. They're marked with a lock icon and a System chip, and every mutating action on them is blocked — you can't rename, archive, merge, or delete a system category (any attempt returns a 422 with a "System cost categories cannot be …" message, and the UI disables the controls).

System categories are:

Category	Role
Base Product	The category for the product's own base cost — the "everything that isn't an added landed cost" bucket
Blank	The undecorated blank in a decorated finished good's layered cost
Decoration Labor	Labor to decorate a made-to-order item
Decoration Consumables	Inks, transfers, and other consumables used in decoration
Decoration Setup	One-off setup / screen / digitizing charges
Outsourced Decoration	A single charge when decoration is subcontracted out

The default user-defined categories SKU seeds (Freight, Customs Duty, Brokerage, Insurance, Handling, Taxes, Other) aren't system — you can rename, archive, merge, or delete those freely.

Decoration and made-to-order categories

The five decoration categories (Blank, Decoration Labor, Decoration Consumables, Decoration Setup, and Outsourced Decoration) exist to compose a decorated finished good's layered cost: a blank plus its consumables, labor, and setup, or a single outsourced-decoration charge. They're seeded idempotently and are system-owned, so they always exist and can't be removed — this keeps the layered-cost buckets stable across every account.

Keyword aliases (landed-cost auto-categorization)

Keyword aliases teach SKU which cost category a line belongs to when it's read off a landed-cost invoice. When an invoice line's description contains a keyword (matched case-insensitively, whole-word), that line is auto-assigned to the keyword's category — so a line reading "BAF / Bunker surcharge" lands under Freight without anyone picking it by hand.

Open the aliases screen from Settings → Financials → Cost Categories → Keyword Aliases.

• The table lists one row per active cost category (archived categories aren't shown here) with its current keywords as chips.
• Add a keyword: click into a category's keyword box, type the word or short code, and press Enter.
• Remove a keyword: click the × on its chip.
• Save the row: click the Save (disk) action on that row. Changes are saved per category — each row saves independently.
• Discard: click Discard changes (undo) to revert a row to its last saved state before saving.

Seeded keywords carry a default flag that distinguishes them from ones you add; any keyword you type is stored as a custom (non-default) keyword.

How keywords are normalized

When you save a category's keywords, SKU cleans the list before storing it:

Rule	Effect
Lowercased & trimmed	Freight becomes freight
Minimum 2 characters	Single-character entries are dropped (the box also validates this and shows "Each keyword must be at least 2 characters.")
Maximum 100 characters	Longer entries are rejected by validation
De-duplicated	Repeats within one category collapse to a single keyword
Replace semantics	Saving replaces that category's whole keyword set — keywords you removed are deleted, and new ones are inserted as custom (non-default)

Ambiguity warning

If the same keyword is assigned to more than one category, the screen shows a Duplicate keywords banner listing them, because a shared keyword produces ambiguous matches at classification time (SKU can't tell which category the line belongs to). Resolve it by removing the keyword from all but one category.

How cost categories connect to inventory and reporting

Cost categories are defined here, but they're consumed elsewhere:

• Landed-cost invoices / bill lines apply a category to each cost line — see add landed costs to a purchase order. Those categorized costs flow into inventory value.
• FIFO cost breakdowns group a product's layered cost by category. The mechanics of layers, COGS, and average cost live in the Inventory guides — see FIFO layers & COGS; this page doesn't re-explain them.
• Financial line types map to categories to drive accounting posting — see set a product's accounting.

Note the difference between a product's unit cost and average cost: unit_cost is the standard cost you enter on a product (see set a product's price), while average_cost is derived from the product's FIFO layers as inventory moves — it's not something you set on this screen, and its detailed mechanics are covered in the FIFO / COGS reference.

Next steps

• Set a product's accounting & financial line type
• Set a product's price
• Add landed costs to a purchase order
• FIFO layers & COGS
• Products — overview