Item Categorizations

The item_categorizations array carries the category path for a catalog item. DoorDash uses it to build where the item sits in in-app browsing, filtering, and category search.

item_categorizations is optional — a catalog job succeeds without it, and an item submitted without it is created normally. Send it whenever you can, though. An item with no category path has no browse placement of its own, so customers reach it only through direct search.

When a path is missing, the DoorDash catalog team attempts to assign a category to every item so it stays searchable and browsable. That assignment is inferred, not authoritative — the categories you send are the strongest input into it. Sharing your own taxonomy keeps items where you expect them rather than where we infer they belong.

The path is expressed as a single recursive structure, not a flat list. sub_category nests inside category, and each sub_category may itself contain another sub_category, up to five levels total.

Field structure

"item_categorizations": [
  {
    "category": {
      "name": "Snacks",
      "sub_category": {
        "name": "Chips"
      }
    }
  }
]

Field definitions

Field	Type	Required	Description
item_categorizations	array	No	Category path for the item. Only the first element is used.
category	object	No	Level 1 of the path. Must be an object if present — null is rejected.
category.name	string	Conditional	Required if category is present. Empty or missing causes the item to be skipped.
category.sub_category	object	No	The next level down. Recursive — nest up to 4 deep inside category for 5 levels total.
sub_category.name	string	Conditional	Required if that sub_category object is present. Same skip behavior as category.name.

Levels 1 and 2 are the customer-facing navigation categories. Levels 3 and beyond are used for backend classification and merchandising.

warning

Only item_categorizations[0] is applied. If you send more than one categorization, DoorDash uses the first as primary and ignores the rest — they are not validated and they do not create additional browse placements. There is no supported way to place one item in two category paths.

Example: minimum viable

A top-level category alone is valid.

"item_categorizations": [
  {
    "category": {
      "name": "Beverages"
    }
  }
]

Example: full five-level path

"item_categorizations": [
  {
    "category": {
      "name": "Beverages",
      "sub_category": {
        "name": "Juice",
        "sub_category": {
          "name": "Fruit Juice",
          "sub_category": {
            "name": "Kids Juice Boxes",
            "sub_category": {
              "name": "Multipacks"
            }
          }
        }
      }
    }
  }
]

Updating categorizations: use POST, not PATCH

item_categorizations is supported on POST only. POST is an upsert, so it works for both new items and items that already exist — that is the supported way to change an item's category path.

Sending item_categorizations on a PATCH fails with Item categorizations update using PATCH is not supported. and drops the whole item.

This is intentional. A category is not a single field, it is a multi-level tree, and a partial tree in a PATCH is ambiguous — there is no way to tell "update this level only" from "this is the complete new category, delete everything below it." Rather than guess and risk corrupting your existing categorization, DoorDash rejects the update. A POST always carries the complete item, so no ambiguity exists.

warning

If you use PATCH for routine attribute updates, strip item_categorizations out of the payload. Leaving it in discards every item it appears on — including the fields you were trying to change. Categorization is the only attribute that behaves this way on PATCH; every other field is validated the same on PATCH as on POST, or produces a warning only.

Only the failing item is dropped. Other items in the same batch are unaffected and ingest normally.

Errors and silent failures

Two failure modes behave very differently, and both return a success-shaped response.

Malformed structure returns 400

Nothing is ingested. The schema is closed, so any unrecognized property is a hard rejection. Common causes:

• subcategory instead of sub_category — the underscore is required.
• Putting sub_category at the same level as category instead of nested inside it.
• "category": null.
• Any additional key inside a category or sub_category object.

Invalid values return a success status, and the item is skipped

The request looks successful — operation_status is QUEUED. The only signal is prose inside message:

{
  "operation_id": "b5e98590-955d-456e-8a49-d2d4fddd0c9d",
  "operation_status": "QUEUED",
  "message": "Request queued. Item validation failed with following errors. Items with errors will be skipped.[item[0]: Multiple item categories found with same name in categorization tree]"
}

Message	Cause	Result
Item category name cannot be null or empty	A category or sub_category object is present with a missing or empty name	Item skipped
Multiple item categories found with same name in categorization tree	The same name appears twice in one path, e.g. Beverages > Juice > Juice	Item skipped
Item categorizations update using PATCH is not supported.	item_categorizations sent on a PATCH request	Item skipped

danger

A skipped item is skipped entirely. Every other field in that item — name, description, images, UPCs, size — is discarded along with the categorization, even though those fields were valid. Always check message for Items with errors will be skipped; do not treat QUEUED as confirmation that anything landed.

Best practices

• Use your own category names. These strings are not validated against a DoorDash taxonomy — there is no list to match against, and unrecognized values do not produce an error.
• Be granular at the deepest level. Prefer Bronzer over Makeup.
• Keep your names consistent across every item and every run. Snacks, snacks, and Snacks are all accepted and all treated as distinct, so casing or whitespace drift silently splits one browse category into several.
• Never repeat a name within a single path — it causes the item to be skipped.
• Send at most five levels. Levels beyond the fifth are dropped with no error.
• Send exactly one categorization per item.