Thanks for being patient while we implement your feedback to improve the developer experience.

Get All Categories

GET /catalog/trees/categories

Request

Returns a list of categories.

To get a specific category in a tree, provide a category ID.

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string - required

    The MIME type of the response body.

  • category_uuid:in in query - string
  • category_uuid:not_in in query - string
  • category_id:in in query - string
  • category_id:not_in in query - string
  • tree_id:in in query - string
  • tree_id:not_in in query - string
  • parent_id:in in query - string
  • parent_id:not_in in query - string
  • name in query - string
  • name:like in query - string
  • page_title in query - string
  • page_title:like in query - string
  • keyword in query - string
  • is_visible in query - boolean
  • page in query - integer
  • limit in query - integer
  • include_fields in query - string
  • exclude_fields in query - string

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/trees/categories' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

List of categories.

Body

object | application/json

  • data    array[object]

  • meta    object

example-1

{
  "data": [
    {
      "id": 0,
      "parent_id": 2,
      "name": "Bath",
      "description": "<p>We offer a wide variety of products perfect for relaxing</p>",
      "views": 1050,
      "sort_order": 3,
      "page_title": "Bath",
      "meta_keywords": [
        "string"
      ],
      "meta_description": "string",
      "layout_file": "category.html",
      "image_url": "https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png",
      "is_visible": true,
      "search_keywords": "string",
      "default_product_sort": "use_store_settings",
      "url": {
        "path": "string",
        "is_customized": true
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 246,
      "count": 5,
      "per_page": 5,
      "current_page": 1,
      "total_pages": 50,
      "links": {
        "previous": "?limit=5&page=1",
        "current": "?limit=5&page=2",
        "next": "?limit=5&page=3"
      }
    }
  }
}

Create Categories

POST /catalog/trees/categories

Request

Creates new categories.

Creating a category requires:

  • name
  • url
  • tree_id or parent_id

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • Content-Type in header with default of application/json - string - required

    The MIME type of the request body.

Body

array | application/json

  • tree_id    integer
    required

  • parent_id    integer
    required

      example

      [
  {
    "tree_id": 0,
    "parent_id": 0,
    "name": "string",
    "description": "string",
    "views": 0,
    "sort_order": 0,
    "page_title": "string",
    "search_keywords": "string",
    "meta_keywords": [
      "string"
    ],
    "meta_description": "string",
    "layout_file": "string",
    "is_visible": true,
    "image_url": "string",
    "custom_url": {
      "url": "string",
      "is_customized": true
    },
    "default_product_sort": "use_store_settings"
  }
]

      Response

      Created

      Body

      object | application/json

      • data        array[object]

      • errors

      • meta        object

      example

      {
  "data": [
    {
      "parent_id": 2,
      "name": "Bath",
      "description": "<p>We offer a wide variety of products perfect for relaxing</p>",
      "views": 1050,
      "sort_order": 3,
      "page_title": "Bath",
      "meta_keywords": [
        "string"
      ],
      "meta_description": "string",
      "layout_file": "category.html",
      "image_url": "https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png",
      "is_visible": true,
      "search_keywords": "string",
      "default_product_sort": "use_store_settings",
      "custom_url": {
        "url": "string",
        "is_customized": true
      }
    }
  ],
  "errors": {
    "status": 0,
    "title": "string",
    "type": "string",
    "errors": {}
  },
  "meta": {
    "total": 0,
    "success": 0,
    "failed": 0
  }
}

      Update Categories

      PUT /catalog/trees/categories

      Request

      Updates existing categories.

      To update a specific category in a tree, provide a category id.

      Authentication

      • X-Auth-Token in header - required

      Parameters

      • store_hash in path - string
      • Content-Type in header with default of application/json - string - required

        The MIME type of the request body.

      Body

      array | application/json

      • tree_id        integer
        required

      • category_id        integer
        required

      • category_uuid        string

      • parent_id        integer

          example

          [
  {
    "tree_id": 0,
    "category_id": 0,
    "category_uuid": "d5e0e6e9-d809-4adf-9920-3a698629ce74",
    "parent_id": 0,
    "name": "string",
    "description": "string",
    "views": 0,
    "sort_order": 0,
    "page_title": "string",
    "search_keywords": "string",
    "meta_keywords": [
      "string"
    ],
    "meta_description": "string",
    "layout_file": "string",
    "is_visible": true,
    "image_url": "string",
    "custom_url": {
      "url": "string",
      "is_customized": true
    },
    "default_product_sort": "use_store_settings"
  }
]

          Response

          OK

          Delete Categories

          DELETE /catalog/trees/categories

          Request

          Deletes categories.

          To delete a specific category in a tree, provide a category ID.

          Authentication

          • X-Auth-Token in header - required

          Parameters

          • store_hash in path - string
          • Accept in header with default of application/json - string - required

            The MIME type of the response body.

          • category_uuid:in in query - string
          • category_id:in in query - string
          • tree_id:in in query - string
          • parent_id:in in query - string

          example

          curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/trees/categories' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

          Response

          Categories are deleted

          Body

          object | application/json

          • meta            object

          example

          {
  "meta": {
    "total": 0,
    "success": 0,
    "failed": 0
  }
}

          Get a Category Tree

          GET /catalog/trees/{tree_id}/categories

          Request

          Returns a Category Tree.

          Authentication

          • X-Auth-Token in header - required

          Parameters

          • store_hash in path - string
          • Accept in header with default of application/json - string - required

            The MIME type of the response body.

          • tree_id in path - string - required
          • depth in query - integer

            Max depth for a tree of categories.

          example

          curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/trees/[tree_id]/categories' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

          Response

          Categories tree

          Body

          object | application/json

          • data            array[object]

          • meta            object

            Response metadata.

          example

          {
  "data": [
    {
      "id": 0,
      "parent_id": 0,
      "depth": 0,
      "path": [
        0
      ],
      "name": "string",
      "is_visible": true,
      "children": [
        "string"
      ]
    }
  ],
  "meta": {
    "type": "object",
    "properties": {},
    "description": "Empty meta object; reserved for use later."
  }
}