Add a product category to Connect

Use the createProductCategory mutation to add a single product category. Two input modes are supported.

Mode B — by category name

Supply categoryName, optionally with parent, categoryId, description, and sourceUrl.

mutation CreateProductCategory {
  createProductCategory(
    category: {
      categoryName: "Survival Kits"
      description: "Survival kit category description"
      sourceUrl: "https://store.com/sporting_goods/camping/survival_kits"
      parent: { id: "cat-coffee-makers" }
    }
  ) {
    id
    categoryId
    categoryName
    description
    sourceUrl
    namespace
    parentId
    calculatedFields { path depth }
    parent { id categoryName }
    tracking { createdAt createdBy lastModifiedAt lastModifiedBy }
  }
}

Mode A — by category path (hierarchical string)

Supply categoryPath as a >-delimited hierarchy string. The leaf (last segment) becomes the new category. categoryName, categoryId, and parent must be omitted. description and sourceUrl are optional and apply to the leaf only.

Optional categoryId prefix: you can supply a customer-defined categoryId for the leaf category by prefixing it to the first segment of the path, separated by a space. In the example below, 123 becomes the categoryId of the leaf Smartphones category.

mutation CreateProductCategoryFromPath {
  createProductCategory(
    category: {
      categoryPath: "123 Electronics > Phones > Smartphones"
      description: "All smartphones"
      sourceUrl: "https://store.com/electronics/phones/smartphones"
    }
  ) {
    id
    categoryId
    categoryName
    description
    sourceUrl
    calculatedFields { depth path }
    parent {
      categoryName
      calculatedFields { depth path }
      parent {
        categoryName
        calculatedFields { depth path }
      }
    }
  }
}

Response

{
  "data": {
    "createProductCategory": {
      "id": "a1b2c3d4-1234-5678-abcd-ef1234567890",
      "categoryId": "123",
      "categoryName": "Smartphones",
      "description": "All smartphones",
      "sourceUrl": "https://store.com/electronics/phones/smartphones",
      "calculatedFields": {
        "path": "Electronics > Phones > Smartphones",
        "depth": 3
      },
      "parent": {
        "categoryName": "Phones",
        "calculatedFields": { "depth": 2, "path": "Electronics > Phones" },
        "parent": {
          "categoryName": "Electronics",
          "calculatedFields": { "depth": 1, "path": "Electronics" }
        }
      }
    }
  }
}

Behavior notes

Sub-categories with the same name under different roots remain independent. "Clothing > Accessories" and "Automotive > Accessories" create two separate Accessories categories.
Existing categories are never re-parented by this mutation.

Error codes

Code	Description
`FEATURE_NOT_ENABLED`	Required feature flag is disabled
`BAD_USER_INPUT`	Both `categoryPath` and `categoryName` supplied; or neither; or `categoryPath` combined with `parent` or `categoryId`
`PARENT_NOT_FOUND`	Specified `parent.id` does not exist
`MAX_DEPTH_EXCEEDED`	The category would exceed the maximum hierarchy depth of 10
`DUPLICATE_CATEGORY_NAME`	A category with this name already exists under the same parent

Authentication

This API uses API Key authentication. See Using the Connect API for instructions on how to get and use your API key.