BigCommerce Sort Order API

openapi: 3.2.0
info:
  title: BigCommerce Catalog - Categories Sort Order API
  description: "\n> The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/docs/store-operations/catalog).\n\n> Warning:\n> - The [Catalog V3 Categories](/docs/rest-catalog/categories) endpoints were primarily useful in applications for single storefront stores and are deprecated. We still support these endpoints, but will not implement new features within them. The endpoints will continue working as is.\n> - To manage Categories, use the [Catalog V3 Category Trees - Categories](/docs/rest-catalog/category-trees/categories) endpoints. These endpoints work for both [MSF-enabled stores](/docs/storefront/multi-storefront) and single storefront stores, and are backwards-compatible with categories created using Catalog V3 Categories.\n\nCategory images have their own dedicated [create a category image](/docs/rest-catalog/categories/images#create-a-category-image) and [delete a category image](/docs/rest-catalog/categories/images#delete-a-category-image) endpoints. \n\nIn addition, categories have metafields that you can use to store information structured in key-value pairs; learn more about [creating category metafields](/docs/rest-catalog/categories/metafields#create-a-category-metafield), [updating category metafields](/docs/rest-catalog/categories/metafields#update-a-category-metafield), and [deleting category metafields](/docs/rest-catalog/categories/metafields#delete-a-category-metafield). \n\nThis API family also contains endpoints to [update product sort order](/docs/rest-catalog/categories/sort-order#update-product-sort-order) within a category. \n\n> To learn more about authenticating Catalog endpoints, locate the **Authentication** section at the top of each endpoint, then click **Show Details**. \n\n## Resources\n\n### Webhooks\nLearn more about [Category webhook events](/docs/integrations/webhooks/events#category).\n\n### Additional Catalog endpoints\n* [Brands](/docs/rest-catalog/brands)\n* [Category Trees](/docs/rest-catalog/category-trees)\n* [Products](/docs/rest-catalog/products)\n* [Product Modifiers](/docs/rest-catalog/product-modifiers)\n* [Product Variants](/docs/rest-catalog/product-variants)\n* [Product Variant Options](/docs/rest-catalog/product-variant-options)"
  termsOfService: https://www.bigcommerce.com/terms
  contact:
    name: BigCommerce
    url: https://www.bigcommerce.com
    email: support@bigcommerce.com
  version: ''
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: Sort Order
paths:
  /catalog/categories/{category_id}/products/sort-order:
    parameters:
    - $ref: '#/components/parameters/Accept'
    - $ref: '#/components/parameters/CategoryIdParam'
    get:
      tags:
      - Sort Order
      summary: BigCommerce Get Product Sort Order
      description: "Returns a list of products and their sort order for a specific category.\n\n**Usage Notes**\n* Data pairs are displayed in ascending order based on products' `sort_order` values.\n* `null` values are allowed for products without specified `sort_order` values.\n* Products with `sort_order` value of `null` will be displayed after products with valid numerical values.\n* The priorities for determining product sort order on a storefront are the following:\n  - Priority 1: Manually specified sort order on Category Level (API).\n  - Priority 2: Manually specified sort order on Product (Global) Level (UI/API).\n  - Priority 3: Default sorting by Product ID (newly added products go first) (UI/API)."
      operationId: getCategorySortOrders
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: Product Sort Order Response
                type: array
                items:
                  $ref: '#/components/schemas/productSortOrder'
        '404':
          description: The requested category was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_Base'
    put:
      tags:
      - Sort Order
      summary: BigCommerce Update Product Sort Order
      description: Updates sort order of products within a specific category.
      operationId: updateCategorySortOrders
      parameters:
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            schema:
              title: Product Sort Order Request
              type: array
              items:
                $ref: '#/components/schemas/productSortOrder'
        required: false
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: Product Sort Order Response
                type: array
                items:
                  $ref: '#/components/schemas/productSortOrder'
        '404':
          description: The requested category was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_Base'
        '422':
          description: 'Unprocessable entity.


            Please verify if all requested products are assigned to the category.


            Please verify if all required fields are present in the request body and are filled with values correctly.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_Base'
      x-codegen-request-body-name: body
components:
  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
    CategoryIdParam:
      name: category_id
      in: path
      description: 'The ID of the `Category` to which the resource belongs.

        '
      required: true
      schema:
        type: integer
    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
  schemas:
    error_Base:
      title: error_Base
      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
      description: 'Error payload for the BigCommerce API.

        '
      x-internal: false
    productSortOrder:
      title: productSortOrder
      required:
      - product_id
      - sort_order
      type: object
      properties:
        product_id:
          minimum: 1
          type: integer
          description: The ID of the associated product.
          example: 99
        sort_order:
          minimum: 0
          type: integer
          example: 4
      description: The relative priority of the product among other products inside the category.
      x-internal: false
  securitySchemes:
    X-Auth-Token:
      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](/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