POST /api/v2/categories
Create an category

Supported Formats

json

Errors

Code Description
401 Unauthorized. Include a WWW-Authenticate header field containing a challenge applicable to the requested resource.
403 Forbidden. The request was a valid request, but the server is refusing to respond to it. 403 error semantically means "unauthorized", i.e. the user does not have the necessary permissions for the resource.
404 Not Found. The requested resource could not be found.
422 Unprocessable Entity. The request was well-formed but was unable to be followed due to semantic errors.
500 Internal Server Error. An unexpected condition was encountered.

Examples

request:
  {
    "category": {
        "path": "Test"
    }
  }

  Sample: create a category with attribute_values

  {
    "category": {
        "path": "Test",
        "attribute_values": [
          {
            "attribute_definition_id": 16,
            "attribute_definition_code": "description",
            "data": "Sample description..."
          }
        ]
    }
  }

  Sample: reset multi shared reference association
  Supported Mode:
  - upsert: default
  - reset: Delete all existing association for this attribute, and replace with the current one. Send empty array to remove all existing values.

  {
    "category": {
        "path": "Test",
        "attribute_values": [
          {
              "attribute_definition_id": 16,
              "attribute_definition_code": "img_desc",
              "data": {
                "associated_code": ["code_1", "code_2"]
              }
              "mode": "reset"
          }
      ]

    }
  }
  Sample: create a category with media items

  {
    "category": {
      "category_set": "Clothing",
      "path": "Shoes",
      "media_items": [
        {
          "media_item_type": "ImageMediaItem",
          "url": "https://www.gettyimages.com.au/gi-resources/images/500px/983801190.jpg",
          "description": "Description",
          "sort_order": 0,
          "is_primary": false,
          "is_uploaded": null,
          "tag_list": []
        }
      ]
    }
  }

  Sample: create a category with entity_identifiers

  {
    "category": {
        "path": "Test",
        "entity_identifiers": [
          {
            "key": "10000000001",
            "name": "Channel Name"
          },
          {
            "key": "20000000002",
            "name": "Channel Name"
          }
        ]
    }
  }

response:
  {
    "id": 3,
    "name": "Test",
    "description": null,
    "parent_id": null,
    "category_set_id": 1,
    "path": null,
    "category_set": {
      "id": 1,
      "name": "default"
    }
  }

Params

Param name Description
category
required

Validations:

  • Must be a Hash
category[category_set]
optional , nil allowed

Category set name. Default is ‘default’ category set. Ignored if parent_id is provided.

Validations:

  • Must be a String
category[path]
optional , nil allowed

Full path of the category including all ancestors. Ignored if name is provided.

Validations:

  • Must be a String
category[name]
optional , nil allowed

Category name

Validations:

  • Must be a String
category[parent_id]
optional , nil allowed

Parent category id

Validations:

  • Must be a Integer
category[description]
optional , nil allowed

Category description

Validations:

  • Must be a String
category[sort_order]
optional , nil allowed

Sort order for category. Must be positive whole number

Validations:

  • Must be a Integer
category[attribute_values]
optional , nil allowed

Attribute values assigned to the Category.

Validations:

  • Must be an array of any type
category[media_items]
optional , nil allowed

Set media items to the entity (existing media items will be removed).

Validations:

  • Must be an Array of nested elements
category[media_items][media_item_type]
optional , nil allowed

Validations:

  • Must be one of: ImageMediaItem, VideoMediaItem, FileMediaItem.
category[media_items][url]
optional , nil allowed

URL that stores the corresponding media item

Validations:

  • Must be a String
category[media_items][description]
optional , nil allowed

Description for the media item

Validations:

  • Must be a String
category[media_items][sort_order_position]
optional , nil allowed

The position of the media item. Non negative integer is supported

Validations:

  • Must be a Integer
category[media_items][is_primary]
optional , nil allowed

Make this media item as primary

Validations:

  • Must be one of: true, false, 1, 0.
category[media_items][tag_list]
optional , nil allowed

Tags for this media item

Validations:

  • Must be an array of String
category[media_items][processing_options]
optional , nil allowed

Options to perform extra image processing on the media item. This is applicable only when media_item_type is ‘ImageMediaItem’

Validations:

  • Must be a Hash
category[media_items][processing_options][apply_background]
optional , nil allowed

Setting this to true would result in a new media item created against the product with background applied. Removes transparency.

Validations:

  • Must be one of: true, false, 1, 0.
category[media_items][processing_options][background_colour]
optional , nil allowed

The colour name or a hex colour code for the background colour for the created media item. Defaults to white.

Validations:

  • Must be a String
category[media_items][processing_options][processed_tags]
optional , nil allowed

The tags for the created media item.

Validations:

  • Must be an array of String