BigCommerce Search Filters API

openapi: 3.2.0
info:
  description: Manage settings and configuration for BigCommerce hosted stores and headless storefronts.
  termsOfService: https://www.bigcommerce.com/terms
  contact:
    name: BigCommerce
    url: https://www.bigcommerce.com
    email: support@bigcommerce.com
  title: BigCommerce Settings V3 Search Filters API
  version: 3.0.0
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
  variables:
    store_hash:
      default: store_hash
      description: Permanent ID of the BigCommerce store.
  description: BigCommerce API Gateway
security:
- X-Auth-Token: []
tags:
- name: Search Filters
paths:
  /settings/search/filters:
    get:
      operationId: getSettingsEnabledSearchFilters
      summary: BigCommerce Get Enabled Filters
      description: Returns a list of enabled default [Product Filtering](https://support.bigcommerce.com/s/article/Product-Filtering-Settings) filters. These filters will be used if a store does not have contextual overrides.
      responses:
        '200':
          description: ''
          content:
            application/json:
              examples:
                example-1:
                  value:
                    data:
                    - collapsed_by_default: false
                      display_name: Size
                      display_product_count: true
                      id: U123=
                      is_enabled: true
                      items_to_show: 10
                      sort_by: alpha
                      type: product
                    - collapsed_by_default: false
                      display_name: Brand
                      display_product_count: true
                      id: Y123=
                      is_enabled: true
                      items_to_show: 12
                      sort_by: alpha
                      type: brand
                    - collapsed_by_default: false
                      display_name: Color
                      display_product_count: true
                      id: Q123=
                      is_enabled: true
                      items_to_show: 10
                      sort_by: alpha
                      type: product
                    - collapsed_by_default: true
                      display_name: Ships for Free
                      display_product_count: false
                      id: Y456=
                      is_enabled: true
                      show_free_shipping_filter: true
                      show_in_stock_filter: true
                      show_is_featured_filter: true
                      type: other
                    meta: {}
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ConfiguredFilters'
                  meta:
                    $ref: '#/components/schemas/MetaOpen'
      tags:
      - Search Filters
    put:
      operationId: updateSettingsEnabledSearchFilters
      summary: BigCommerce Update Enabled Filters
      description: Updates enabled default [Product Filtering](https://support.bigcommerce.com/s/article/Product-Filtering-Settings) filters.
      parameters:
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            examples:
              example-1:
                value:
                - collapsed_by_default: false
                  display_name: Size
                  display_product_count: true
                  id: U123=
                  is_enabled: true
                  items_to_show: 12
                  sort_by: alpha
                  type: product
                - collapsed_by_default: false
                  display_name: Brand
                  display_product_count: true
                  id: Y123=
                  is_enabled: true
                  items_to_show: 10
                  sort_by: alpha
                  type: brand
                - collapsed_by_default: false
                  display_name: Color
                  display_product_count: true
                  id: Q123=
                  is_enabled: true
                  items_to_show: 10
                  sort_by: alpha
                  type: product
                - collapsed_by_default: true
                  display_name: Ships for Free
                  display_product_count: true
                  id: Y456=
                  is_enabled: true
                  show_free_shipping_filter: true
                  show_in_stock_filter: true
                  show_is_featured_filter: true
                  type: other
            schema:
              $ref: '#/components/schemas/ConfiguredFilters'
      responses:
        '200':
          description: ''
          content:
            application/json:
              examples:
                example-1:
                  value:
                    data:
                    - collapsed_by_default: false
                      display_name: Size
                      display_product_count: true
                      id: U123==
                      is_enabled: true
                      items_to_show: 12
                      sort_by: alpha
                      type: product
                    - collapsed_by_default: false
                      display_name: Brand
                      display_product_count: true
                      id: Y123=
                      is_enabled: true
                      items_to_show: 10
                      sort_by: alpha
                      type: brand
                    - collapsed_by_default: false
                      display_name: Color
                      display_product_count: true
                      id: Q123=
                      is_enabled: true
                      items_to_show: 10
                      sort_by: alpha
                      type: product
                    - collapsed_by_default: true
                      display_name: Ships for Free
                      display_product_count: true
                      id: Y456=
                      is_enabled: true
                      show_free_shipping_filter: true
                      show_in_stock_filter: true
                      show_is_featured_filter: true
                      type: other
                    meta: {}
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ConfiguredFilters'
                  meta:
                    $ref: '#/components/schemas/MetaOpen'
      tags:
      - Search Filters
  /settings/search/filters/available:
    parameters:
    - $ref: '#/components/parameters/Accept'
    get:
      operationId: getSettingsAvailableFilters
      summary: BigCommerce Get Available Filters
      description: Returns a list of filters available to power [Product Filtering](https://support.bigcommerce.com/s/article/Product-Filtering-Settings).
      parameters:
      - $ref: '#/components/parameters/ContentType'
      - name: channel_id
        in: query
        description: Narrows the list of available filters based on channel ID. Only products currently assigned to the given Channel will be considered.
        schema:
          type: integer
      - name: category_id
        in: query
        description: Narrows the list of available filters based on category ID. You can display settings to show products from the provided category, subcategories only, or both the category and its child categories.
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              examples:
                example-1:
                  value:
                    data:
                    - id: Y2F0Zooo123=
                      name: Category
                      product_count: 7
                      type: category
                    - id: YnJh123=
                      name: Brand
                      product_count: 8
                      type: brand
                    - id: cmF0a123
                      name: Rating
                      product_count: 1
                      type: rating
                    - id: cHJp123=
                      name: Price
                      price_range_max: 300.99
                      price_range_min: 6.75
                      type: price
                    - id: U2l123==
                      name: Size
                      product_count: 3
                      type: product
                    - id: Q29s123=
                      name: Color
                      product_count: 2
                      type: product
                    - id: Ym9123==
                      name: Other
                      type: other
                    meta: {}
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AvailableFilter'
                  meta:
                    $ref: '#/components/schemas/MetaOpen'
      tags:
      - Search Filters
  /settings/search/filters/contexts:
    parameters:
    - $ref: '#/components/parameters/Accept'
    get:
      operationId: getSettingsFiltersContexts
      summary: BigCommerce Get Contextual Filters
      description: 'Returns a list of contextual filters enabled for a particular channel or category.


        **Usage Notes**


        Contextual filters allow you to configure the enabled filters per channel or category, so that shoppers can filter by the most relevant criteria.


        The order of the returned filters will match the sort order of the filters on the storefront.'
      parameters:
      - name: channel_id
        in: query
        description: Only return contextual overrides related to a particular Channel.
        schema:
          type: integer
      - name: category_id
        in: query
        description: Only return contextual overrides related to a particular Category.
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConfiguredFiltersOverride'
                  meta:
                    $ref: '#/components/schemas/MetaPaginationObject'
      tags:
      - Search Filters
    put:
      operationId: upsertSettingsFiltersContexts
      summary: BigCommerce Upsert Contextual Filters
      description: 'Upserts contextual filters for a particular channel or category.


        **Usage Notes**


        Contextual filters allow you to configure the enabled filters per channel or category, so that shoppers can filter by the most relevant criteria.


        You can change the order of the filters on the live site by changing the order of the filters you send.'
      parameters:
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ConfiguredFiltersOverride'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConfiguredFiltersOverride'
                  meta:
                    $ref: '#/components/schemas/MetaOpen'
      tags:
      - Search Filters
components:
  schemas:
    MetaOpen:
      title: Response meta
      type: object
      properties: {}
      additionalProperties: true
      description: Response metadata.
    ConfiguredFilter:
      oneOf:
      - $ref: '#/components/schemas/EnabledProductFilter'
      - $ref: '#/components/schemas/EnabledPriceFilter'
      - $ref: '#/components/schemas/EnabledCategoryFilter'
      - $ref: '#/components/schemas/EnabledBrandFilter'
      - $ref: '#/components/schemas/EnabledRatingFilter'
      - $ref: '#/components/schemas/EnabledMiscFilter'
      title: ConfiguredFilter
      x-internal: false
    AvailablePriceFilter:
      description: ''
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        price_range_max:
          type: number
        price_range_min:
          type: number
        type:
          type: string
          enum:
          - price
      title: AvailablePriceFilter
      x-internal: false
    AvailableOtherFilter:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum:
          - other
      title: AvailableOtherFilter
      x-internal: false
    EnabledMiscFilter:
      description: Miscellaneous Filters which appear as a group.
      type: object
      properties:
        collapsed_by_default:
          type: boolean
        display_name:
          type: string
        display_product_count:
          type: boolean
        id:
          type: integer
        is_enabled:
          type: boolean
        show_free_shipping_filter:
          type: boolean
        show_in_stock_filter:
          type: boolean
        show_is_featured_filter:
          type: boolean
        show_product_count:
          type: boolean
        type:
          type: string
          enum:
          - other
      title: EnabledMiscFilter
      x-internal: false
    ConfiguredFiltersOverride:
      description: A new set of enabled Product Filtering filters which should display in a particular context, such as on a particular Channel, or while viewing a particular Category. Array order indicates the display order on the storefront.
      type: object
      properties:
        context:
          $ref: '#/components/schemas/SearchFilterOverrideContextIdentifier'
        data:
          $ref: '#/components/schemas/ConfiguredFilters'
      title: ConfiguredFiltersOverride
      x-internal: false
    EnabledPriceFilter:
      description: A filter based on the product’s price, shown as a price range on the storefront.
      type: object
      properties:
        collapsed_by_default:
          type: boolean
        display_name:
          type: string
        id:
          type: string
        is_enabled:
          type: boolean
        type:
          type: string
          enum:
          - price
      title: EnabledPriceFilter
      x-internal: false
    ConfiguredFilters:
      type: array
      items:
        $ref: '#/components/schemas/ConfiguredFilter'
      title: ConfiguredFilters
      x-internal: false
    AvailableNormalFilter:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        product_count:
          type: integer
        type:
          type: string
          enum:
          - category
          - brand
          - rating
          - product
      title: AvailableNormalFilter
      x-tags:
      - Models
    SearchFilterOverrideContextIdentifier:
      type: object
      properties:
        category_id:
          type: integer
        channel_id:
          type: integer
      title: ContextIdentifier
      x-internal: false
    AvailableFilter:
      type: object
      oneOf:
      - $ref: '#/components/schemas/AvailableNormalFilter'
      - $ref: '#/components/schemas/AvailablePriceFilter'
      - $ref: '#/components/schemas/AvailableOtherFilter'
      title: AvailableFilter
      x-internal: false
    EnabledBrandFilter:
      description: A storefront filter for product brand
      type: object
      properties:
        collapsed_by_default:
          type: boolean
        display_name:
          type: string
        display_product_count:
          type: boolean
        id:
          type: string
        is_enabled:
          type: boolean
        items_to_show:
          type: integer
          enum:
          - 5
          - 10
          - 15
        sort_by:
          type: string
          enum:
          - alpha
          - item_count
        type:
          type: string
          enum:
          - brand
      title: EnabledBrandFilter
      x-internal: false
    EnabledRatingFilter:
      description: A filter based on product review ratings.
      type: object
      properties:
        collapsed_by_default:
          type: boolean
        display_name:
          type: string
        id:
          type: string
        is_enabled:
          type: boolean
        type:
          type: string
          enum:
          - rating
      title: EnabledRatingFilter
      x-internal: false
    MetaPaginationObject:
      type: object
      properties:
        pagination:
          type: object
          properties:
            count:
              type: integer
              example: 5
              minimum: 0
            current_page:
              type: integer
              example: 1
              minimum: 1
            links:
              type: object
              properties:
                current:
                  type: string
                  example: ?limit=5&page=1
                next:
                  type: string
                  example: ?limit=5&page=2
            per_page:
              type: integer
              example: 5
              minimum: 0
            total:
              type: integer
              example: 246
              minimum: 0
            total_pages:
              type: integer
              example: 50
              minimum: 0
      x-internal: false
    EnabledCategoryFilter:
      description: A storefront filter for product category
      type: object
      properties:
        collapsed_by_default:
          type: boolean
        display_name:
          type: string
        display_product_count:
          type: boolean
        id:
          type: string
        is_enabled:
          type: boolean
        items_to_show:
          type: integer
          enum:
          - 5
          - 10
          - 15
        type:
          type: string
          enum:
          - category
      title: EnabledCategoryFilter
      x-internal: false
    EnabledProductFilter:
      description: A filter that uses product options and custom field data.
      type: object
      properties:
        collapsed_by_default:
          type: boolean
        display_name:
          type: string
        display_product_count:
          type: boolean
        id:
          type: string
        is_enabled:
          type: boolean
        items_to_show:
          type: integer
          enum:
          - 5
          - 10
          - 15
        sort_by:
          type: string
          enum:
          - alpha
          - option_values
          - item_count
        type:
          type: string
          enum:
          - product
      title: EnabledProductFilter
      x-internal: false
  parameters:
    Accept:
      name: Accept
      in: header
      required: true
      description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.
      schema:
        type: string
        default: application/json
    ContentType:
      name: Content-Type
      in: header
      required: true
      description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.
      schema:
        type: string
        default: application/json
  securitySchemes:
    X-Auth-Token:
      name: X-Auth-Token
      description: '### OAuth scopes


        | UI Name | Permission | Parameter |

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

        |  Information & Settings | modify | `store_v2_information` |

        |  Information & Settings | read-only | `store_v2_information_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](/docs/start/authentication/api-accounts). |


        ### Further reading


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


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


        For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes).'
      type: apiKey
      in: header