DEVDOCS-5575 [update]: Catalog API, categories (#18)

Co-authored-by: Sarah Riehl <[email protected]>

docs/api-docs/getting-started/deprecations-and-sunsets.mdx

@@ -9,13 +9,14 @@ This article provides a reference for deprecated APIs and exposes BigCommerce's
 
 ## Deprecations
 
-The following APIs, features, and tools are deprecated. We discourage using these listed items, as BigCommerce no longer supports them. Instead, consider using the suggested replacements.
+The following APIs, features, and tools are deprecated. We discourage using these listed items, as BigCommerce either no longer supports them or won't be providing additional support or new features. Instead, consider using the suggested replacements.
 
 | Deprecated API or feature | Replacement |
 |:--------------------------|:------------|
 | `/v2/brands` | [Catalog V3 Brands](/docs/rest-catalog/brands#get-all-brands) |
 | `/v3/content/widgets/search` | [Widgets V3, Get all widgets](/docs/rest-content/widgets/widget#get-all-widgets) |
-| `/v2/categories` | [Catalog V3 Categories](/docs/rest-catalog/categories#get-all-categories) |
+| `/v2/categories` | [Catalog V3 Catalog Trees - Categories](/docs/rest-catalog/category-trees/categories#get-all-categories) |
+| `/v3/catalog/categories` | [Catalog V3 Catalog Trees - Categories](/docs/rest-catalog/category-trees/categories#get-all-categories) |
 | `/v2/customers` | [Customers V3](/docs/rest-management/customers) |
 | `/v3/hooks/events`| [Get Events](/docs/webhooks/webhooks/webhook-events#get-events) |
 | `/v2/options` | [Catalog V3 Product Modifiers](/docs/rest-catalog/product-modifiers#get-all-product-modifiers), [Catalog V3 Product Variant Options](/docs/rest-catalog/product-variant-options#get-all-product-variant-options). See the [Accessing product options](#accessing-product-options-with-V3) callout. |

docs/legacy/v2-catalog-products/v2-categories.mdx

@@ -12,7 +12,7 @@ Index of hierarchical categories used to organize and group products.
 <Callout type="warning">
   #### Deprecated
   Avoid using this API operation if possible. It will be removed in a future version.
-  For the most up-to-date version of this API, see [Category](/docs/rest-catalog/categories).
+  For the most up-to-date version of this API, see [Catalog V3 Catalog Trees - Categories](/docs/rest-catalog/category-trees/categories).
 </Callout>
 
 ### Category Object – Properties 

reference/catalog/categories_catalog.v3.yml

@@ -2,18 +2,19 @@ openapi: '3.0.3'
 info:
   title: Catalog - Categories
   description: |-
+    
     > 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).
-
-    Our Catalog Categories endpoints let you [create individual categories](/docs/rest-catalog/categories#create-a-category) and [modify categories](/docs/rest-catalog/categories#update-a-category) that organize a store's products, as well as [delete categories](/docs/rest-catalog/categories#delete-a-category). 
+    
+    > Warning:
+    > - 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.
+    > - 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.
     
     Category 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. 
     
     In 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). 
 
     This API family also contains endpoints to [update product sort order](/docs/rest-catalog/categories/sort-order#update-product-sort-order) within a category. 
 
-    These endpoints are primarily useful in applications for single storefront stores. To work with categories for an [MSF-enabled store](/docs/storefront/multi-storefront), see [Category Trees](/docs/rest-catalog/category-trees).
-
     > To learn more about authenticating Catalog endpoints, locate the **Authentication** section at the top of each endpoint, then click **Show Details**. 
 
     ## Resources
@@ -45,17 +46,20 @@ servers:
 security:
   - X-Auth-Token: []
 tags:
-  - name: Categories
   - name: Metafields
   - name: Images
   - name: Sort Order
+  - name: Categories (deprecated)
 paths:
   '/catalog/categories':
     get:
       tags:
-        - Categories
+        - Categories (deprecated)
+      deprecated: true
       summary: Get All Categories
       description: |-
+        When possible, use the [Catalog Trees - Get all categories](/docs/rest-catalog/category-trees/categories#get-all-categories) endpoint instead.
+
         Returns a list of *Categories*. Optional filter parameters can be passed in.
 
         **Note:**
@@ -367,9 +371,10 @@ paths:
                       current: '?page=1&limit=50'
     post:
       tags:
-        - Categories
+        - Categories (deprecated)
+      deprecated: true
       summary: Create a Category
-      description: "Creates a *Category*.\n\nUse this endpoint when an API only works with categories of a default BigCommerce storefront (`channel_id=1`). \n\nUse the [Create Categories](/docs/rest-catalog/category-trees/categories#create-categories) endpoint when an API works with categories across different category trees that belong to different storefront channels.\n\n**Required Fields**:\n- `parent_id`: \n\t- To create a child category, set the `parent_id` to the parent category.\n\t- To create a top level category, set the `parent_id` to `0`.\n- `name`\n\n**Read-Only Fields**:\n- `id`\n\n**Limits**:\n- 16,000 categories per store limit.\n- 1,000 categories per product limit.\n- 50 characters category name length.\n- 8 levels of category depth limit.\n- 65,642 characters category description length limit.\n\n **Note:**\n The default rate limit for this endpoint is 40 concurrent requests.\n"
+      description: "When possible, use the [Category Trees - Create categories](/docs/rest-catalog/category-trees/categories#create-categories) endpoint instead.\n\nCreates a *Category*.\n\nUse this endpoint when an API only works with categories of a default BigCommerce storefront (`channel_id=1`). \n\nUse the [Create categories](/docs/rest-catalog/category-trees/categories#create-categories) endpoint when an API works with categories across different category trees that belong to different storefront channels.\n\n**Required Fields**:\n- `parent_id`: \n\t- To create a child category, set the `parent_id` to the parent category.\n\t- To create a top level category, set the `parent_id` to `0`.\n- `name`\n\n**Read-Only Fields**:\n- `id`\n\n**Limits**:\n- 16,000 categories per store limit.\n- 1,000 categories per product limit.\n- 50 characters category name length.\n- 8 levels of category depth limit.\n- 65,642 characters category description length limit.\n\n **Note:**\n The default rate limit for this endpoint is 40 concurrent requests.\n"
       operationId: createCategory
       parameters:
         - $ref: '#/components/parameters/ContentType'
@@ -573,9 +578,12 @@ paths:
       x-codegen-request-body-name: category
     delete:
       tags:
-        - Categories
+        - Categories (deprecated)
+      deprecated: true
       summary: Delete Categories
       description: |-
+        When possible, use the [Category Trees - Delete categories](/docs/rest-catalog/category-trees/categories#delete-categories) endpoint instead.
+
         Deletes *Category* objects. At least one filter parameter is required to perform the `DELETE` operation.
 
         **Usage Notes**
@@ -729,9 +737,12 @@ paths:
   '/catalog/categories/{category_id}':
     get:
       tags:
-        - Categories
+        - Categories (deprecated)
+      deprecated: true
       summary: Get a Category
       description: |-
+        When possible, use the [Catalog Trees - Get all categories](/docs/rest-catalog/category-trees/categories#get-all-categories) endpoint instead. You can provide a category identifier using query parameters to retrieve a single category.
+
         Returns a single *Category*. Optional parameters can be passed in.
 
         **Note:**
@@ -784,9 +795,12 @@ paths:
                 description: Error payload for the BigCommerce API.
     put:
       tags:
-        - Categories
+        - Categories (deprecated)
+      deprecated: true
       summary: Update a Category
       description: |-
+        When possible, use the [Catalog Trees - Update categories](/docs/rest-catalog/category-trees/categories#update-categories) endpoint instead.
+
         Updates a *Category*.
 
         **Required Fields**
@@ -1148,9 +1162,12 @@ paths:
       x-codegen-request-body-name: category
     delete:
       tags:
-        - Categories
+        - Categories (deprecated)
+      deprecated: true
       summary: Delete a Category
       description: |-
+        When possible, use the [Category Trees - Delete categories](/docs/rest-catalog/category-trees/categories#delete-categories) endpoint instead. You can provide a category identifier using query parameters to delete a single category.
+
         Deletes a *Category*.
         
         **Note:**

reference/catalog/category-trees_catalog.v3.yml

@@ -4,7 +4,7 @@ info:
   description: |-
     > 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).
 
-    Our Catalog Category Trees endpoints are the more modern and performant counterparts to the [Categories endpoints](/docs/rest-catalog/categories). Although the Category Trees endpoints and objects are designed to center an MSF-compatible, [multi-tenant category tree architecture](#categories), the endpoints work just as well in a single storefront context.
+    Our Catalog Category Trees and their [Categories](/docs/rest-catalog/category-trees/categories) endpoints are the more modern and performant counterparts to the [Categories (deprecated)](/docs/rest-catalog/categories) endpoints. Although the Category Trees endpoints and objects are designed to center an MSF-compatible, [multi-tenant category tree architecture](#categories), the endpoints work just as well in a single storefront context and support batch requests. Use [Catalog Trees Categories](/docs/rest-catalog/category-trees/categories) endpoints, instead of [Categories (deprecated)](/docs/rest-catalog/categories) endpoints.
 
     The Category Trees endpoints let you [get the Categories for a specific tree](/docs/rest-catalog/category-trees/categories#get-a-category-tree), and [bulk create](/docs/rest-catalog/category-trees/categories#create-categories), [bulk update](/docs/rest-catalog/category-trees/categories#update-categories), and [bulk delete](/docs/rest-catalog/category-trees/categories#delete-categories) Categories. You can also [bulk update the properties of Category Trees](/docs/rest-catalog/category-trees#upsert-category-trees), which includes changing the channels to which a Tree is assigned.
 
@@ -515,7 +515,7 @@ paths:
                   additionalProp2: string
                   additionalProp3: string
       tags:
-        - Categories
+        - Category Trees
     parameters:
       - $ref: '#/components/parameters/Accept'
       - schema: