openapi: 3.1.0
info:
  title: 'Admin Catalog: Category Trees'
  version: 1.0.0
paths:
  /stores/{store_hash}/v3/catalog/trees:
    get:
      operationId: getCategoryTrees
      summary: List Category Trees
      description: Returns a list of category trees.
      tags:
        - categoryTrees
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: id:in
          in: query
          description: Filter by supplying a comma-separated list of category tree IDs.
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: channel_id:in
          in: query
          description: Filter by supplying a comma-separated list of channel IDs.
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: List of category trees.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryTreeList'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCategoryTreesRequestUnprocessableEntityError'
    put:
      operationId: upsertCategoryTrees
      summary: Upsert Category Trees
      description: >
        Upserts category trees. 


        This single endpoint updates and creates category trees. If a tree object contains an ID, it is processed as an
        update operation using that ID. If you do not provide an ID, a new tree is created. The category tree `name`
        field is required to create trees, but is not required on the update.


        **Usage Notes**

        * Channel ID in the `channels` field is required to create a category tree. You can only assign a category tree
        to one channel.

        * The `channels` field must be absent when updating a category tree. This field is currently unsupported during
        a category tree update.
      tags:
        - categoryTrees
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: Created a category tree.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryTree'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        '422':
          description: The Channel was not valid. See the response for more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/beta4ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryTreeListRequest'
    delete:
      operationId: deleteCategoryTrees
      summary: Delete Category Trees
      description: Deletes category trees. A filter must be supplied with the endpoint.
      tags:
        - categoryTrees
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: id:in
          in: query
          description: Filter by supplying a comma-separated list of category tree IDs.
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '204':
          description: Deleted
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteCategoryTreesRequestUnprocessableEntityError'
  /stores/{store_hash}/v3/catalog/trees/{tree_id}/categories:
    get:
      operationId: getCategoryTree
      summary: Get Category Tree
      description: |-
        Returns a category tree.

        **Note:**
        The default rate limit for this endpoint is 1 concurrent request.
      tags:
        - categoryTrees
      parameters:
        - name: tree_id
          in: path
          description: The ID of the category tree.
          required: true
          schema:
            type: integer
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: depth
          in: query
          description: Max depth for a tree of categories.
          required: false
          schema:
            type: integer
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: Categories tree
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryNodeTree'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        '404':
          description: The tree was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/beta4ErrorResponse'
  /stores/{store_hash}/v3/catalog/trees/categories:
    get:
      operationId: getAllCategories
      summary: List Categories
      description: |-
        Returns a list of categories. 

        To get a specific category in a tree, provide a category ID.
      tags:
        - categories
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: category_uuid:in
          in: query
          description: >-
            Filter using a comma-separated list of one or more category UUIDs. To use category IDs, use the
            `category_id:in` parameter.
          required: false
          schema:
            type: array
            items:
              type: string
              format: uuid
        - name: category_uuid:not_in
          in: query
          description: >-
            Filter using a comma-separated list to exclude one or more category UUIDs. To exclude using category IDs,
            use the `category_id:not_in` parameter.
          required: false
          schema:
            type: array
            items:
              type: string
              format: uuid
        - name: category_id:in
          in: query
          description: >-
            Filter using a comma-separated list of one or more category IDs. To use category UUIDs, use the
            `category_uuid:in` parameter.
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: category_id:not_in
          in: query
          description: >-
            Filter using a comma-separated list to exclude one or more category IDs. To exclude using category UUIDs,
            use the `category_uuid:not_in` parameter.
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: tree_id:in
          in: query
          description: Filter using a comma-separated list of one or more category tree IDs.
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: tree_id:not_in
          in: query
          description: Filter using a comma-separated list to exclude one or more category tree IDs.
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: parent_id:in
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: parent_id:not_in
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: page_title
          in: query
          description: |
            Filter items by page_title.
          required: false
          schema:
            type: string
        - name: page_title:like
          in: query
          description: >-
            Filter items by substring in the page title property. `page_title:like=oil` returns both `Soil and mulch`
            and `Oil pastels`.
          required: false
          schema:
            type: string
        - name: name
          in: query
          description: |
            Filter items by name.
          required: false
          schema:
            type: string
        - name: name:like
          in: query
          description: >-
            Filter items by substring in the name property. `name:like=stick` returns both `Stickers` and `Lipstick
            colors`.
          required: false
          schema:
            type: string
        - name: keyword
          in: query
          description: Filter items by keywords found in the `name`, `description`, or `sku` fields, or in the brand name.
          required: false
          schema:
            type: string
        - name: is_visible
          in: query
          description: Filter items based on whether the product is currently visible on the storefront.
          required: false
          schema:
            type: boolean
        - name: include_fields
          in: query
          description: Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: exclude_fields
          in: query
          description: >-
            Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID
            cannot be excluded.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: page
          in: query
          description: |
            Specifies the page number in a limited (paginated) list of products.
          required: false
          schema:
            type: integer
        - name: limit
          in: query
          description: |
            Controls the number of items per page in a limited (paginated) list of products.
          required: false
          schema:
            type: integer
            default: 50
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: List of categories.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryList'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAllCategoriesRequestUnprocessableEntityError'
    post:
      operationId: createCategories
      summary: Create Categories
      description: |-
        Creates new categories. 

        Limits: 
        - 16,000 categories per store limit.
        - 1,000 categories per product limit.
        - 50 characters category name length.
        - 8 levels of child categories depth limit.
        - 65,535 characters category description length limit.

        Creating a category requires:
         - `name`
         - `tree_id` or `parent_id`
         - The `url` property is optional, but if included, its path must be unique per channel and category. If the path is not unique, the category will still be created but the URL will not — the response returns a multi-status to indicate the partial success.
      tags:
        - categories
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRequest'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        '422':
          description: >-
            The Category was not valid. This is the result of missing required fields, or of invalid data. See the
            response for more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCategories'
    put:
      operationId: updateCategories
      summary: Update Categories
      description: >-
        Updates existing categories. 


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


        The `url` property is optional, but if included, its path must be unique per channel and category. If the path
        is not unique, the category will still be created but the URL will not — the response returns a multi-status to
        indicate the partial success.
      tags:
        - categories
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessNoContentResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRequest'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        '422':
          description: >-
            The Category was not valid. This is the result of missing required fields, or of invalid data. See the
            response for more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCategories'
    delete:
      operationId: deleteTreeCategories
      summary: Delete Categories
      description: |-
        Deletes categories. 

        To delete a specific category in a tree, provide a category ID.
      tags:
        - categories
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: category_uuid:in
          in: query
          description: >-
            Filter using a comma-separated list of one or more category UUIDs. To use category IDs, use the
            `category_id:in` parameter.
          required: false
          schema:
            type: array
            items:
              type: string
              format: uuid
        - name: category_id:in
          in: query
          description: >-
            Filter using a comma-separated list of one or more category IDs. To use category UUIDs, use the
            `category_uuid:in` parameter.
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: tree_id:in
          in: query
          description: Filter using a comma-separated list of one or more category tree IDs.
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: parent_id:in
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '202':
          description: Categories are deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessNoContentResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRequest'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteTreeCategoriesRequestUnprocessableEntityError'
servers:
  - url: https://api.bigcommerce.com
    description: https://api.bigcommerce.com
components:
  schemas:
    Tree:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        channels:
          type: array
          items:
            type: integer
      title: Tree
    MetaPaginationObjectPaginationLinks:
      type: object
      properties:
        next:
          type: string
        current:
          type: string
      title: MetaPaginationObjectPaginationLinks
    MetaPaginationObjectPagination:
      type: object
      properties:
        total:
          type: integer
        count:
          type: integer
        per_page:
          type: integer
        current_page:
          type: integer
        total_pages:
          type: integer
        links:
          $ref: '#/components/schemas/MetaPaginationObjectPaginationLinks'
      title: MetaPaginationObjectPagination
    MetaPaginationObject:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/MetaPaginationObjectPagination'
      title: MetaPaginationObject
    CategoryTreeList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Tree'
        meta:
          $ref: '#/components/schemas/MetaPaginationObject'
      title: CategoryTreeList
    GeneralError:
      type: object
      properties:
        status:
          type: integer
          description: The HTTP status code.
        title:
          type: string
          description: The error title describes the particular error.
        type:
          type: string
        code:
          type: integer
          description: The custom code of the error.
      required:
        - status
        - title
        - type
      title: GeneralError
    GeneralErrorWithErrorsErrors:
      type: object
      properties: {}
      title: GeneralErrorWithErrorsErrors
    GeneralErrorWithErrors:
      type: object
      properties:
        status:
          type: integer
          description: The HTTP status code.
        title:
          type: string
          description: The error title describing the particular error.
        type:
          type: string
        errors:
          $ref: '#/components/schemas/GeneralErrorWithErrorsErrors'
      required:
        - status
        - title
        - type
        - errors
      title: GeneralErrorWithErrors
    MetaData:
      type: object
      properties:
        total:
          type: integer
        success:
          type: integer
        failed:
          type: integer
      title: MetaData
    GetCategoryTreesRequestUnprocessableEntityError:
      type: object
      properties:
        errors:
          $ref: '#/components/schemas/GeneralErrorWithErrors'
        meta:
          $ref: '#/components/schemas/MetaData'
      title: GetCategoryTreesRequestUnprocessableEntityError
    CategoryTreeListRequest:
      type: array
      items:
        $ref: '#/components/schemas/Tree'
      title: CategoryTreeListRequest
    metaEmpty_Full:
      type: object
      properties: {}
      description: Response metadata.
      title: metaEmpty_Full
    CategoryTree:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Tree'
        meta:
          $ref: '#/components/schemas/metaEmpty_Full'
      title: CategoryTree
    beta4DetailedErrors:
      type: object
      properties: {}
      title: beta4DetailedErrors
    beta4ErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: |
            The HTTP status code.
        title:
          type: string
          description: |
            The error title describing the particular error.
        type:
          type: string
        instance:
          type: string
        errors:
          $ref: '#/components/schemas/beta4DetailedErrors'
      description: |
        Error payload for the BigCommerce API.
      title: beta4ErrorResponse
    DeleteCategoryTreesRequestUnprocessableEntityError:
      type: object
      properties:
        errors:
          $ref: '#/components/schemas/GeneralErrorWithErrors'
        meta:
          $ref: '#/components/schemas/MetaData'
      title: DeleteCategoryTreesRequestUnprocessableEntityError
    CategoryNode:
      type: object
      properties:
        id:
          type: integer
        parent_id:
          type: integer
        depth:
          type: integer
        path:
          type: array
          items:
            type: integer
        name:
          type: string
        is_visible:
          type: boolean
        children:
          type: array
          items:
            $ref: '#/components/schemas/CategoryNode'
        url:
          type: string
      title: CategoryNode
    CategoryNodeTree:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CategoryNode'
        meta:
          $ref: '#/components/schemas/metaEmpty_Full'
      title: CategoryNodeTree
    name:
      type: string
      description: |-
        The name displayed for the category. Name is unique with respect to the categoryʼs siblings.
        Required in a POST.
      title: name
    category_id:
      type: integer
      description: Unique ID of the *Category*. Increments sequentially.
      title: category_id
    category_uuid:
      type: string
      format: uuid
      description: An additional unique identifier for the category. Read-Only.
      title: category_uuid
    tree_id:
      type: integer
      description: >-
        The ID of the category tree. To create a top-level category, specify the `tree_id`. Otherwise, you can specify
        the `parent_id`.
      title: tree_id
    parent_id:
      type: integer
      description: >-
        The unique numeric ID of the category parent. To create a top-level category, specify the `tree_id`. Otherwise,
        you can specify the `parent_id`. Required in a POST if creating a child category.
      title: parent_id
    GetCategoriesDefaultProductSort:
      type: string
      enum:
        - use_store_settings
        - featured
        - newest
        - best_selling
        - alpha_asc
        - alpha_desc
        - avg_customer_review
        - price_asc
        - price_desc
      description: |
        Determines how the products are sorted on category page load.
      title: GetCategoriesDefaultProductSort
    url:
      type: object
      properties:
        path:
          type: string
        is_customized:
          type: boolean
      description: |
        If not provided in POST request, the URL is autogenerated from the category name.
      title: url
    GetCategories:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/name'
        category_id:
          $ref: '#/components/schemas/category_id'
        category_uuid:
          $ref: '#/components/schemas/category_uuid'
        tree_id:
          $ref: '#/components/schemas/tree_id'
        parent_id:
          $ref: '#/components/schemas/parent_id'
        description:
          type: string
          description: |
            The product description, which can include HTML formatting.
        views:
          type: integer
          description: |
            Number of views the category has on the storefront.
        sort_order:
          type: integer
          description: >
            Priority this category will be given when included in the menu and category pages. The lower the number, the
            closer to the top of the results the category will be.
        page_title:
          type: string
          description: |
            Custom title for the category page. If not defined, the category name will be used as the meta title.
        meta_keywords:
          type: array
          items:
            type: string
          description: >
            Custom meta keywords for the category page. If not defined, the storeʼs default keywords will be used. Must
            post as an array like: ["awesome","sauce"].
        meta_description:
          type: string
          description: >
            Custom meta description for the category page. If not defined, the storeʼs default meta description will be
            used.
        layout_file:
          type: string
          description: >
            A valid layout file. (Please refer to [this
            article](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/) on creating
            category files.) This field is writable only for stores with a Blueprint theme applied.
        image_url:
          type: string
          description: >
            Image URL used for this category on the storefront. Images can be uploaded via form file post to
            `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. Must be either a
            full-qualified URL or an empty string.
        is_visible:
          type: boolean
          description: >
            Flag to determine whether the product should be displayed to customers browsing the store. If `true`, the
            category will be displayed. If `false`, the category will be hidden from view.
        search_keywords:
          type: string
          description: |
            A comma-separated list of keywords that can be used to locate the category when searching the store.
        default_product_sort:
          $ref: '#/components/schemas/GetCategoriesDefaultProductSort'
          description: |
            Determines how the products are sorted on category page load.
        url:
          $ref: '#/components/schemas/url'
      title: GetCategories
    MetaPaginationPaginationLinks:
      type: object
      properties:
        previous:
          type: string
        current:
          type: string
        next:
          type: string
      title: MetaPaginationPaginationLinks
    MetaPaginationPagination:
      type: object
      properties:
        total:
          type: integer
        count:
          type: integer
        per_page:
          type: integer
        current_page:
          type: integer
        total_pages:
          type: integer
        links:
          $ref: '#/components/schemas/MetaPaginationPaginationLinks'
      title: MetaPaginationPagination
    MetaPagination:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/MetaPaginationPagination'
      title: MetaPagination
    CategoryList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/GetCategories'
        meta:
          $ref: '#/components/schemas/MetaPagination'
      title: CategoryList
    GetAllCategoriesRequestUnprocessableEntityError:
      type: object
      properties:
        errors:
          $ref: '#/components/schemas/GeneralErrorWithErrors'
        meta:
          $ref: '#/components/schemas/MetaData'
      title: GetAllCategoriesRequestUnprocessableEntityError
    CreateCategoriesItemsDefaultProductSort:
      type: string
      enum:
        - use_store_settings
        - featured
        - newest
        - best_selling
        - alpha_asc
        - alpha_desc
        - avg_customer_review
        - price_asc
        - price_desc
      description: |
        Determines how the products are sorted on category page load.
      title: CreateCategoriesItemsDefaultProductSort
    CreateCategoriesItems:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/name'
        url:
          $ref: '#/components/schemas/url'
        parent_id:
          $ref: '#/components/schemas/parent_id'
        tree_id:
          $ref: '#/components/schemas/tree_id'
        description:
          type: string
          description: |
            The product description, which can include HTML formatting.
        views:
          type: integer
          description: |
            Number of views the category has on the storefront.
        sort_order:
          type: integer
          description: >
            Priority this category will be given when included in the menu and category pages. The lower the number, the
            closer to the top of the results the category will be.
        page_title:
          type: string
          description: |
            Custom title for the category page. If not defined, the category name will be used as the meta title.
        meta_keywords:
          type: array
          items:
            type: string
          description: >
            Custom meta keywords for the category page. If not defined, the storeʼs default keywords will be used. Must
            post as an array like: ["awesome","sauce"].
        meta_description:
          type: string
          description: >
            Custom meta description for the category page. If not defined, the storeʼs default meta description will be
            used.
        layout_file:
          type: string
          description: >
            A valid layout file. (Please refer to [this
            article](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/) on creating
            category files.) This field is writable only for stores with a Blueprint theme applied.
        image_url:
          type: string
          description: >
            Image URL used for this category on the storefront. Images can be uploaded via form file post to
            `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. Must be either a
            full-qualified URL or an empty string.
        is_visible:
          type: boolean
          description: >
            Flag to determine whether the product should be displayed to customers browsing the store. If `true`, the
            category will be displayed. If `false`, the category will be hidden from view.
        search_keywords:
          type: string
          description: |
            A comma-separated list of keywords that can be used to locate the category when searching the store.
        default_product_sort:
          $ref: '#/components/schemas/CreateCategoriesItemsDefaultProductSort'
          description: |
            Determines how the products are sorted on category page load.
      required:
        - name
      title: CreateCategoriesItems
    CreateCategories:
      type: array
      items:
        $ref: '#/components/schemas/CreateCategoriesItems'
      title: CreateCategories
    SuccessResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/GetCategories'
        meta:
          $ref: '#/components/schemas/MetaData'
      title: SuccessResponse
    ErrorBasic:
      type: object
      properties:
        status:
          type: integer
          description: |
            The HTTP status code.
        title:
          type: string
          description: |
            The error title describing the particular error.
        type:
          type: string
      title: ErrorBasic
    ErrorRequest:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorBasic'
      title: ErrorRequest
    DetailedErrors:
      type: object
      properties: {}
      description: Each key-value pair describes a failure or partial success case.
      title: DetailedErrors
    MetaError:
      type: object
      properties:
        status:
          type: integer
          description: |
            The HTTP status code.
        title:
          type: string
          description: |
            The error title describing the particular error.
        type:
          type: string
        errors:
          $ref: '#/components/schemas/DetailedErrors'
      title: MetaError
    ErrorResponse:
      type: object
      properties:
        errors:
          $ref: '#/components/schemas/MetaError'
        meta:
          $ref: '#/components/schemas/MetaData'
      title: ErrorResponse
    UpdateCategoriesItemsDefaultProductSort:
      type: string
      enum:
        - use_store_settings
        - featured
        - newest
        - best_selling
        - alpha_asc
        - alpha_desc
        - avg_customer_review
        - price_asc
        - price_desc
      description: |
        Determines how the products are sorted on category page load.
      title: UpdateCategoriesItemsDefaultProductSort
    UpdateCategoriesItems:
      type: object
      properties:
        category_id:
          $ref: '#/components/schemas/category_id'
        name:
          $ref: '#/components/schemas/name'
        tree_id:
          $ref: '#/components/schemas/tree_id'
        parent_id:
          $ref: '#/components/schemas/parent_id'
        description:
          type: string
          description: |
            The product description, which can include HTML formatting.
        views:
          type: integer
          description: |
            Number of views the category has on the storefront.
        sort_order:
          type: integer
          description: >
            Priority this category will be given when included in the menu and category pages. The lower the number, the
            closer to the top of the results the category will be.
        page_title:
          type: string
          description: |
            Custom title for the category page. If not defined, the category name will be used as the meta title.
        meta_keywords:
          type: array
          items:
            type: string
          description: >
            Custom meta keywords for the category page. If not defined, the storeʼs default keywords will be used. Must
            post as an array like: ["awesome","sauce"].
        meta_description:
          type: string
          description: >
            Custom meta description for the category page. If not defined, the storeʼs default meta description will be
            used.
        layout_file:
          type: string
          description: >
            A valid layout file. (Please refer to [this
            article](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/) on creating
            category files.) This field is writable only for stores with a Blueprint theme applied.
        image_url:
          type: string
          description: >
            Image URL used for this category on the storefront. Images can be uploaded via form file post to
            `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. Must be either a
            full-qualified URL or an empty string.
        is_visible:
          type: boolean
          description: >
            Flag to determine whether the product should be displayed to customers browsing the store. If `true`, the
            category will be displayed. If `false`, the category will be hidden from view.
        search_keywords:
          type: string
          description: |
            A comma-separated list of keywords that can be used to locate the category when searching the store.
        default_product_sort:
          $ref: '#/components/schemas/UpdateCategoriesItemsDefaultProductSort'
          description: |
            Determines how the products are sorted on category page load.
        url:
          $ref: '#/components/schemas/url'
      required:
        - category_id
      title: UpdateCategoriesItems
    UpdateCategories:
      type: array
      items:
        $ref: '#/components/schemas/UpdateCategoriesItems'
      title: UpdateCategories
    SuccessNoContentResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/MetaData'
      title: SuccessNoContentResponse
    DeleteTreeCategoriesRequestUnprocessableEntityError:
      type: object
      properties:
        errors:
          $ref: '#/components/schemas/GeneralErrorWithErrors'
        meta:
          $ref: '#/components/schemas/MetaData'
      title: DeleteTreeCategoriesRequestUnprocessableEntityError
  securitySchemes:
    X-Auth-Token:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: >-
        ### OAuth scopes


        | UI Name | Permission | Parameter |

        |:--------|:-----------|:----------|

        |  Products | modify | `store_v2_products` |

        |  Products | read-only | `store_v2_products_read_only` |


        ### Authentication header


        | Header | Argument | Description |

        |:-------|:---------|:------------|

        | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to
        API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


        ### Further reading


        For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example
        Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


        For more about BigCommerce OAuth scopes, see our [Guide to API
        Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


        For a list of API status codes, see [API Status
        Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
